Skip to contentSkip to conversation

mm: modest useability enhancements for node sysfs attrs

PATCH Superseded Alex Chiang 3 participants 15 messages Oct 19, 2009 – Oct 21, 2009

Subsystems (3)

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

cover mm: modest useability enhancements for node sysfs attrs

I've been poking at memory/node hotplug lately, and found myself wondering what node a memory section or CPU might belong to.

Yes, the information is there in sysfs, but to me, having a symlink pointing back to the node is so much more convenient.

Thanks,
/ac

---

Alex Chiang (5):
mm: add numa node symlink for memory section in sysfs
mm: refactor register_cpu_under_node()
mm: refactor unregister_cpu_under_node()
mm: add numa node symlink for cpu devices in sysfs
Documentation: ABI: document /sys/devices/system/cpu/

 Documentation/ABI/testing/sysfs-devices-cpu    |   42 ++++++++++++++++++
 Documentation/ABI/testing/sysfs-devices-memory |   14 ++++++
 Documentation/memory-hotplug.txt               |   11 +++--
 drivers/base/node.c                            |   56 +++++++++++++++++-------
 4 files changed, 102 insertions(+), 21 deletions(-)
 create mode 100644 Documentation/ABI/testing/sysfs-devices-cpu
#1 lore raw

PATCH 1/5 mm: add numa node symlink for memory section in sysfs

Commit c04fc586c (mm: show node to memory section relationship with symlinks in sysfs) created symlinks from nodes to memory sections, e.g.

/sys/devices/system/node/node1/memory135 -> ../../memory/memory135

If you're examining the memory section though and are wondering what node it might belong to, you can find it by grovelling around in sysfs, but it's a little cumbersome.

Add a reverse symlink for each memory section that points back to the node to which it belongs.

Cc Gary Hade <[email protected]>
Cc Badari Pulavarty <[email protected]>
Cc Ingo Molnar <[email protected]>

---

 Documentation/ABI/testing/sysfs-devices-memory |   14 +++++++++++++-
 Documentation/memory-hotplug.txt               |   11 +++++++----
 drivers/base/node.c                            |   11 ++++++++++-
 3 files changed, 30 insertions(+), 6 deletions(-)
Documentation/ABI/testing/sysfs-devices-memory +13 -1
index 9fe91c0..bf1627b 100644
@@ -60,6 +60,19 @@ Description:
 Users:		hotplug memory remove tools
 		https://w3.opensource.ibm.com/projects/powerpc-utils/
 
+
+What:		/sys/devices/system/memoryX/nodeY
+Date:		October 2009
+Contact:	Linux Memory Management list <[email protected]>
+Description:
+		When CONFIG_NUMA is enabled, a symbolic link that
+		points to the corresponding NUMA node directory.
+
+		For example, the following symbolic link is created for
+		memory section 9 on node0:
+		/sys/devices/system/memory/memory9/node0 -> ../../node/node0
+
+
 What:		/sys/devices/system/node/nodeX/memoryY
 Date:		September 2008
 Contact:	Gary Hade <[email protected]>
@@ -70,4 +83,3 @@ Description:
 		memory section directory.  For example, the following symbolic
 		link is created for memory section 9 on node0.
 		/sys/devices/system/node/node0/memory9 -> ../../memory/memory9
-
Documentation/memory-hotplug.txt +7 -4
index bbc8a6a..57e7e9c 100644
@@ -160,12 +160,15 @@ Under each section, you can see 4 files.
 NOTE:
   These directories/files appear after physical memory hotplug phase.
 
-If CONFIG_NUMA is enabled the
-/sys/devices/system/memory/memoryXXX memory section
-directories can also be accessed via symbolic links located in
-the /sys/devices/system/node/node* directories.  For example:
+If CONFIG_NUMA is enabled the memoryXXX/ directories can also be accessed
+via symbolic links located in the /sys/devices/system/node/node* directories.
+
+For example:
 /sys/devices/system/node/node0/memory9 -> ../../memory/memory9
 
+A backlink will also be created:
+/sys/devices/system/memory/memory9/node0 -> ../../node/node0
+
 --------------------------------
 4. Physical memory hot-add phase
 --------------------------------
drivers/base/node.c +10 -1
index 1fe5536..3108b21 100644
@@ -268,6 +268,7 @@ static int get_nid_for_pfn(unsigned long pfn)
 /* register memory section under specified node if it spans that node */
 int register_mem_sect_under_node(struct memory_block *mem_blk, int nid)
 {
+	int ret;
 	unsigned long pfn, sect_start_pfn, sect_end_pfn;
 
 	if (!mem_blk)
@@ -284,9 +285,15 @@ int register_mem_sect_under_node(struct memory_block *mem_blk, int nid)
 			continue;
 		if (page_nid != nid)
 			continue;
-		return sysfs_create_link_nowarn(&node_devices[nid].sysdev.kobj,
+		ret = sysfs_create_link_nowarn(&node_devices[nid].sysdev.kobj,
 					&mem_blk->sysdev.kobj,
 					kobject_name(&mem_blk->sysdev.kobj));
+		if (ret)
+			return ret;
+
+		return sysfs_create_link_nowarn(&mem_blk->sysdev.kobj,
+				&node_devices[nid].sysdev.kobj,
+				kobject_name(&node_devices[nid].sysdev.kobj));
 	}
 	/* mem section does not span the specified node */
 	return 0;
@@ -315,6 +322,8 @@ int unregister_mem_sect_under_nodes(struct memory_block *mem_blk)
 			continue;
 		sysfs_remove_link(&node_devices[nid].sysdev.kobj,
 			 kobject_name(&mem_blk->sysdev.kobj));
+		sysfs_remove_link(&mem_blk->sysdev.kobj,
+			 kobject_name(&node_devices[nid].sysdev.kobj));
 	}
 	return 0;
 }
#2 lore raw

Re: [PATCH 1/5] mm: add numa node symlink for memory section in sysfs

Quoted 9 lines · Alex Chiang

Commit c04fc586c (mm: show node to memory section relationship with symlinks in sysfs) created symlinks from nodes to memory sections, e.g.

/sys/devices/system/node/node1/memory135 -> ../../memory/memory135

If you're examining the memory section though and are wondering what node it might belong to, you can find it by grovelling around in sysfs, but it's a little cumbersome.

Quoted 7 lines

Add a reverse symlink for each memory section that points back to the node to which it belongs.

Cc Gary Hade <[email protected]>
Cc Badari Pulavarty <[email protected]>
Cc Ingo Molnar <[email protected]>

2 yeas ago, I wanted to add this symlink. But don't...because some vendor's host has no 1-to-1 relationship between a memsection and a node. (I don't remember precisely, sorry....s390?)

Then, a memsection can be under prural nodes.

At brief look, this patch provides 1-to-1 relationship between them. If it's ok for all stake-holders, I welcome this.

Thanks,
-Kame

Quoted 110 lines

---

 Documentation/ABI/testing/sysfs-devices-memory |   14 +++++++++++++-
 Documentation/memory-hotplug.txt               |   11 +++++++----
 drivers/base/node.c                            |   11 ++++++++++-
 3 files changed, 30 insertions(+), 6 deletions(-)
Documentation/ABI/testing/sysfs-devices-memory +13 -1
index 9fe91c0..bf1627b 100644
@@ -60,6 +60,19 @@ Description:
 Users:		hotplug memory remove tools
 		https://w3.opensource.ibm.com/projects/powerpc-utils/
 
+
+What:		/sys/devices/system/memoryX/nodeY
+Date:		October 2009
+Contact:	Linux Memory Management list <[email protected]>
+Description:
+		When CONFIG_NUMA is enabled, a symbolic link that
+		points to the corresponding NUMA node directory.
+
+		For example, the following symbolic link is created for
+		memory section 9 on node0:
+		/sys/devices/system/memory/memory9/node0 -> ../../node/node0
+
+
 What:		/sys/devices/system/node/nodeX/memoryY
 Date:		September 2008
 Contact:	Gary Hade <[email protected]>
@@ -70,4 +83,3 @@ Description:
 		memory section directory.  For example, the following symbolic
 		link is created for memory section 9 on node0.
 		/sys/devices/system/node/node0/memory9 -> ../../memory/memory9
-
Documentation/memory-hotplug.txt +2 -4
index bbc8a6a..57e7e9c 100644
@@ -160,12 +160,15 @@ Under each section, you can see 4 files.
 NOTE:
   These directories/files appear after physical memory hotplug phase.
 
-If CONFIG_NUMA is enabled the
-/sys/devices/system/memory/memoryXXX memory section
-directories can also be accessed via symbolic links located in
-the /sys/devices/system/node/node* directories.  For example:
+If CONFIG_NUMA is enabled the memoryXXX/ directories can also be accessed
+via symbolic links located in the /sys/devices/system/node/node*

directories.

Documentation/memory-hotplug.txt +5 -0
+
+For example:
 /sys/devices/system/node/node0/memory9 -> ../../memory/memory9
 
+A backlink will also be created:
+/sys/devices/system/memory/memory9/node0 -> ../../node/node0
+
 --------------------------------
 4. Physical memory hot-add phase
 --------------------------------
drivers/base/node.c +8 -1
index 1fe5536..3108b21 100644
@@ -268,6 +268,7 @@ static int get_nid_for_pfn(unsigned long pfn)
 /* register memory section under specified node if it spans that node */
 int register_mem_sect_under_node(struct memory_block *mem_blk, int nid)
 {
+	int ret;
 	unsigned long pfn, sect_start_pfn, sect_end_pfn;
 
 	if (!mem_blk)
@@ -284,9 +285,15 @@ int register_mem_sect_under_node(struct memory_block
 *mem_blk, int nid)
 			continue;
 		if (page_nid != nid)
 			continue;
-		return sysfs_create_link_nowarn(&node_devices[nid].sysdev.kobj,
+		ret = sysfs_create_link_nowarn(&node_devices[nid].sysdev.kobj,
 					&mem_blk->sysdev.kobj,
 					kobject_name(&mem_blk->sysdev.kobj));
+		if (ret)
+			return ret;
+
+		return sysfs_create_link_nowarn(&mem_blk->sysdev.kobj,
+				&node_devices[nid].sysdev.kobj,
+				kobject_name(&node_devices[nid].sysdev.kobj));
 	}
 	/* mem section does not span the specified node */
drivers/base/node.c +2 -0
 	return 0;
@@ -315,6 +322,8 @@ int unregister_mem_sect_under_nodes(struct
 memory_block *mem_blk)
 			continue;
 		sysfs_remove_link(&node_devices[nid].sysdev.kobj,
 			 kobject_name(&mem_blk->sysdev.kobj));
+		sysfs_remove_link(&mem_blk->sysdev.kobj,
+			 kobject_name(&node_devices[nid].sysdev.kobj));
 	}
 	return 0;

}

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/

#3 lore raw

Re: [PATCH 1/5] mm: add numa node symlink for memory section in sysfs

* KAMEZAWA Hiroyuki <[email protected]>:

Quoted 13 lines
Quoted 12 lines · Alex Chiang

Commit c04fc586c (mm: show node to memory section relationship with symlinks in sysfs) created symlinks from nodes to memory sections, e.g.

/sys/devices/system/node/node1/memory135 -> ../../memory/memory135

If you're examining the memory section though and are wondering what node it might belong to, you can find it by grovelling around in sysfs, but it's a little cumbersome.

Add a reverse symlink for each memory section that points back to the node to which it belongs.

Quoted 8 lines
Quoted 4 lines
Cc Gary Hade <[email protected]>
Cc Badari Pulavarty <[email protected]>
Cc Ingo Molnar <[email protected]>

2 yeas ago, I wanted to add this symlink. But don't...because some vendor's host has no 1-to-1 relationship between a memsection and a node. (I don't remember precisely, sorry....s390?)

Hm, ok. I'll cc the s390 folks in the next version of this series.

Thanks for the pointer.

/ac

#4 lore raw

PATCH 2/5 mm: refactor register_cpu_under_node()

In reply to Alex Chiang

By returning early if the node is not online, we can unindent the interesting code by one level.

No functional change.

---

 drivers/base/node.c |   20 +++++++++++---------
 1 files changed, 11 insertions(+), 9 deletions(-)
drivers/base/node.c +11 -9
index 3108b21..ef7dd22 100644
@@ -227,16 +227,18 @@ struct node node_devices[MAX_NUMNODES];
  */
 int register_cpu_under_node(unsigned int cpu, unsigned int nid)
 {
-	if (node_online(nid)) {
-		struct sys_device *obj = get_cpu_sysdev(cpu);
-		if (!obj)
-			return 0;
-		return sysfs_create_link(&node_devices[nid].sysdev.kobj,
-					 &obj->kobj,
-					 kobject_name(&obj->kobj));
-	 }
+	struct sys_device *obj;
 
-	return 0;
+	if (!node_online(nid))
+		return 0;
+
+	obj = get_cpu_sysdev(cpu);
+	if (!obj)
+		return 0;
+
+	return sysfs_create_link(&node_devices[nid].sysdev.kobj,
+				&obj->kobj,
+				kobject_name(&obj->kobj));
 }
 
 int unregister_cpu_under_node(unsigned int cpu, unsigned int nid)
#5 lore raw

PATCH 3/5 mm: refactor unregister_cpu_under_node()

In reply to Alex Chiang

By returning early if the node is not online, we can unindent the interesting code by two levels.

No functional change.

---

 drivers/base/node.c |   18 ++++++++++++------
 1 files changed, 12 insertions(+), 6 deletions(-)
drivers/base/node.c +12 -6
index ef7dd22..ffda067 100644
@@ -243,12 +243,18 @@ int register_cpu_under_node(unsigned int cpu, unsigned int nid)
 
 int unregister_cpu_under_node(unsigned int cpu, unsigned int nid)
 {
-	if (node_online(nid)) {
-		struct sys_device *obj = get_cpu_sysdev(cpu);
-		if (obj)
-			sysfs_remove_link(&node_devices[nid].sysdev.kobj,
-					 kobject_name(&obj->kobj));
-	}
+	struct sys_device *obj;
+
+	if (!node_online(nid))
+		return 0;
+
+	obj = get_cpu_sysdev(cpu);
+	if (!obj)
+		return 0;
+
+	sysfs_remove_link(&node_devices[nid].sysdev.kobj,
+			  kobject_name(&obj->kobj));
+
 	return 0;
 }
 

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in the body to [email protected]. For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"[email protected]"> [email protected] </a>

#6 lore raw

PATCH 4/5 mm: add numa node symlink for cpu devices in sysfs

In reply to Alex Chiang

You can discover which CPUs belong to a NUMA node by examining /sys/devices/system/node/$node/

However, it's not convenient to go in the other direction, when looking at /sys/devices/system/cpu/$cpu/

Yes, you can muck about in sysfs, but adding these symlinks makes life a lot more convenient.

---

 drivers/base/node.c |    9 ++++++++-
 1 files changed, 8 insertions(+), 1 deletions(-)
drivers/base/node.c +8 -1
index ffda067..47a4997 100644
@@ -227,6 +227,7 @@ struct node node_devices[MAX_NUMNODES];
  */
 int register_cpu_under_node(unsigned int cpu, unsigned int nid)
 {
+	int ret;
 	struct sys_device *obj;
 
 	if (!node_online(nid))
@@ -236,9 +237,13 @@ int register_cpu_under_node(unsigned int cpu, unsigned int nid)
 	if (!obj)
 		return 0;
 
-	return sysfs_create_link(&node_devices[nid].sysdev.kobj,
+	ret = sysfs_create_link(&node_devices[nid].sysdev.kobj,
 				&obj->kobj,
 				kobject_name(&obj->kobj));
+
+	return sysfs_create_link(&obj->kobj,
+				 &node_devices[nid].sysdev.kobj,
+				 kobject_name(&node_devices[nid].sysdev.kobj));
 }
 
 int unregister_cpu_under_node(unsigned int cpu, unsigned int nid)
@@ -254,6 +259,8 @@ int unregister_cpu_under_node(unsigned int cpu, unsigned int nid)
 
 	sysfs_remove_link(&node_devices[nid].sysdev.kobj,
 			  kobject_name(&obj->kobj));
+	sysfs_remove_link(&obj->kobj,
+			  kobject_name(&node_devices[nid].sysdev.kobj));
 
 	return 0;
 }
#7 lore raw

Re: [PATCH 4/5] mm: add numa node symlink for cpu devices in sysfs

Quoted 3 lines · Alex Chiang

You can discover which CPUs belong to a NUMA node by examining /sys/devices/system/node/$node/

You mean /sys/devices/system/node/node# ?

Quoted 3 lines

However, it's not convenient to go in the other direction, when looking at /sys/devices/system/cpu/$cpu/

.../cpu/cpu# ?

Quoted 26 lines

Yes, you can muck about in sysfs, but adding these symlinks makes life a lot more convenient.

---

 drivers/base/node.c |    9 ++++++++-
 1 files changed, 8 insertions(+), 1 deletions(-)
drivers/base/node.c +1 -1
index ffda067..47a4997 100644
@@ -227,6 +227,7 @@ struct node node_devices[MAX_NUMNODES];
  */
 int register_cpu_under_node(unsigned int cpu, unsigned int nid)
 {
+	int ret;
 	struct sys_device *obj;
 
 	if (!node_online(nid))
@@ -236,9 +237,13 @@ int register_cpu_under_node(unsigned int cpu, unsigned int nid)
 	if (!obj)
 		return 0;
 
-	return sysfs_create_link(&node_devices[nid].sysdev.kobj,

drivers/base/node.c int register_cpu_under_node(unsigned int cpu, unsigned int nid) · line 249

Quoted 10 lines
drivers/base/node.c +5 -0
+	ret = sysfs_create_link(&node_devices[nid].sysdev.kobj,
 				&obj->kobj,
 				kobject_name(&obj->kobj));
+
+	return sysfs_create_link(&obj->kobj,
+				 &node_devices[nid].sysdev.kobj,
+				 kobject_name(&node_devices[nid].sysdev.kobj));
 }
 
 int unregister_cpu_under_node(unsigned int cpu, unsigned int nid)

That can't be right, you're ignoring the return value of the first sysfs_create_link().

The return values of register_cpu_under_node() and unregister_cpu_under_node() are always ignored, so it would probably be best to convert these to be void functions. That doesn't mean you can simply ignore the result of the first sysfs_create_link(), though: the second should probably be suppressed if the first returns an error.

#8 lore raw

Re: [PATCH 4/5] mm: add numa node symlink for cpu devices in sysfs

* David Rientjes <[email protected]>:

Quoted 7 lines · Alex Chiang
Quoted 4 lines

You can discover which CPUs belong to a NUMA node by examining /sys/devices/system/node/$node/

You mean /sys/devices/system/node/node# ?

Hm, in PCI land, I've been using $foo to indicate a variable in documentation I've written, but I can certainly use foo# if that's the preferred style.

Quoted 41 lines
Quoted 3 lines

However, it's not convenient to go in the other direction, when looking at /sys/devices/system/cpu/$cpu/

.../cpu/cpu# ?

Quoted 35 lines

Yes, you can muck about in sysfs, but adding these symlinks makes life a lot more convenient.

---

 drivers/base/node.c |    9 ++++++++-
 1 files changed, 8 insertions(+), 1 deletions(-)
drivers/base/node.c +6 -1
index ffda067..47a4997 100644
@@ -227,6 +227,7 @@ struct node node_devices[MAX_NUMNODES];
  */
 int register_cpu_under_node(unsigned int cpu, unsigned int nid)
 {
+	int ret;
 	struct sys_device *obj;
 
 	if (!node_online(nid))
@@ -236,9 +237,13 @@ int register_cpu_under_node(unsigned int cpu, unsigned int nid)
 	if (!obj)
 		return 0;
 
-	return sysfs_create_link(&node_devices[nid].sysdev.kobj,
+	ret = sysfs_create_link(&node_devices[nid].sysdev.kobj,
 				&obj->kobj,
 				kobject_name(&obj->kobj));
+
+	return sysfs_create_link(&obj->kobj,
+				 &node_devices[nid].sysdev.kobj,
+				 kobject_name(&node_devices[nid].sysdev.kobj));
 }
 
Quoted 4 lines

drivers/base/node.c int register_cpu_under_node(unsigned int cpu, unsigned int nid) · line 249

Quoted 1 line
drivers/base/node.c +0 -0
 int unregister_cpu_under_node(unsigned int cpu, unsigned int nid)

That can't be right, you're ignoring the return value of the first sysfs_create_link().

This was a simple oversight. my intent was to return early if the first call to sysfs_create_link() failed.

Quoted 6 lines

The return values of register_cpu_under_node() and unregister_cpu_under_node() are always ignored, so it would probably be best to convert these to be void functions. That doesn't mean you can simply ignore the result of the first sysfs_create_link(), though: the second should probably be suppressed if the first returns an error.

I didn't want to change too much in the patch. Changing the function signature seems a bit overeager, but if you have strong feelings, I can do so.

Thanks for the review.

/ac

#9 lore raw

Re: [PATCH 4/5] mm: add numa node symlink for cpu devices in sysfs

Quoted 7 lines · Alex Chiang

* David Rientjes <[email protected]>:

Quoted 6 lines · Alex Chiang
Quoted 4 lines

You can discover which CPUs belong to a NUMA node by examining /sys/devices/system/node/$node/

Quoted 6 lines
Quoted 1 line

You mean /sys/devices/system/node/node# ?

Hm, in PCI land, I've been using $foo to indicate a variable in documentation I've written, but I can certainly use foo# if that's the preferred style.

I'm referring to the directories in /sys/devices/system/node/ being 'node13' for example, and not '13' as your changelog indicates.

Quoted 6 lines
Quoted 6 lines
Quoted 3 lines

However, it's not convenient to go in the other direction, when looking at /sys/devices/system/cpu/$cpu/

.../cpu/cpu# ?

Same here.

Quoted 11 lines
Quoted 6 lines

The return values of register_cpu_under_node() and unregister_cpu_under_node() are always ignored, so it would probably be best to convert these to be void functions. That doesn't mean you can simply ignore the result of the first sysfs_create_link(), though: the second should probably be suppressed if the first returns an error.

I didn't want to change too much in the patch. Changing the function signature seems a bit overeager, but if you have strong feelings, I can do so.

It's entirely up to you if you want to change them to be void. I thought it would be cleaner if the first patch in the series would convert them to void on the basis that the return value is never actually used and then the following patches simply return on error conditions.

#10 lore raw

Re: [PATCH 4/5] mm: add numa node symlink for cpu devices in sysfs

* David Rientjes <[email protected]>:

Quoted 8 lines · Alex Chiang
Quoted 7 lines

* David Rientjes <[email protected]>:

Quoted 5 lines

The return values of register_cpu_under_node() and unregister_cpu_under_node() are always ignored, so it would probably be best to convert these to be void functions. That doesn't mean you can simply ignore the result of the first sysfs_create_link(), though: the second should probably be suppressed if the first returns an error.

Quoted 8 lines
Quoted 3 lines

I didn't want to change too much in the patch. Changing the function signature seems a bit overeager, but if you have strong feelings, I can do so.

It's entirely up to you if you want to change them to be void. I thought it would be cleaner if the first patch in the series would convert them to void on the basis that the return value is never actually used and then the following patches simply return on error conditions.

I made the conversion as you suggested, but discovered under sparse that:

drivers/base/node.c: In function ‘register_cpu_under_node’:
drivers/base/node.c:245: warning: ignoring return value of ‘sysfs_create_link’, declared with attribute warn_unused_result

I wasn't very happy with the result after doing something with the return value of sysfs_create_link to make sparse shutup. Seemed unnatural and very much had the feeling of jumping through hoops just to make an automated tool be quiet.

So, I'll just leave [un]register_cpu_under_node() as returning int. It not only makes the patch feel better, but if we do ever want to decide to unroll due to an error in sysfs_create_link, we'll have the information available at the callsites.

Thanks.
/ac

#11 lore raw

PATCH 5/5 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.

Since I wanted to extend the ABI, I figured I would document what already existed.

---

 Documentation/ABI/testing/sysfs-devices-cpu |   42 +++++++++++++++++++++++++++
 1 files changed, 42 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/ABI/testing/sysfs-devices-cpu
Documentation/ABI/testing/sysfs-devices-cpu new file +42 -0
new file mode 100644
index 0000000..9070889
@@ -0,0 +1,42 @@
+What:		/sys/devices/system/cpu/
+Date:		October 2009
+Contact:	Linux kernel mailing list <[email protected]>
+Description:
+		A collection of CPU attributes, including cache information,
+		topology, and frequency. It also contains a mechanism to
+		logically hotplug CPUs.
+
+		The actual attributes present are architecture and
+		configuration dependent.
+
+
+What:		/sys/devices/system/cpu/$cpu/online
+Date:		January 2006
+Contact:	Linux kernel mailing list <[email protected]>
+Description:
+		When CONFIG_HOTPLUG_CPU is enabled, allows the user to
+		discover and change the online state of a CPU. To discover
+		the state:
+
+		cat /sys/devices/system/cpu/$cpu/online
+
+		A value of 0 indicates the CPU is offline. A value of 1
+		indicates it is online. To change the state, echo the
+		desired new state into the file:
+
+		echo [0|1] > /sys/devices/system/cpu/$cpu/online
+
+		For more information, please read Documentation/cpu-hotplug.txt
+
+
+What:		/sys/devices/system/cpu/$cpu/node
+Date:		October 2009
+Contact:	Linux memory management mailing list <[email protected]>
+Description:
+		When CONFIG_NUMA is enabled, a symbolic link that points
+		to the corresponding NUMA node directory.
+
+		For example, the following symlink is created for cpu42
+		in NUMA node 2:
+
+		/sys/devices/system/cpu/cpu42/node2 -> ../../node/node2
#12 lore raw

Re: [PATCH 5/5] Documentation: ABI: document /sys/devices/system/cpu/

Documentation/ABI/testing/sysfs-devices-cpu

Quoted 5 lines · Alex Chiang
Documentation/ABI/testing/sysfs-devices-cpu new file +0 -0
new file mode 100644
index 0000000..9070889

Shouldn't this be called sysfs-devices-system-cpu?

I see what you're doing: /sys/devices/system/node/* files are contained in sysfs-devices-memory, but I think it would be helpful to have a more strict naming scheme so that the contents of a sysfs directory are described by a file of the same name.

Quoted 4 lines
Documentation/ABI/testing/sysfs-devices-cpu new file +3 -0
@@ -0,0 +1,42 @@
+What:		/sys/devices/system/cpu/
+Date:		October 2009
+Contact:	Linux kernel mailing list <[email protected]>

Documentation/ABI/testing/sysfs-devices-cpu line 13

Quoted 10 lines
Documentation/ABI/testing/sysfs-devices-cpu new file +10 -0
+Description:
+		A collection of CPU attributes, including cache information,
+		topology, and frequency. It also contains a mechanism to
+		logically hotplug CPUs.
+
+		The actual attributes present are architecture and
+		configuration dependent.
+
+
+What:		/sys/devices/system/cpu/$cpu/online

cpu# ?

Documentation/ABI/testing/sysfs-devices-cpu line 19

Quoted 6 lines
Documentation/ABI/testing/sysfs-devices-cpu new file +6 -0
+Date:		January 2006
+Contact:	Linux kernel mailing list <[email protected]>
+Description:
+		When CONFIG_HOTPLUG_CPU is enabled, allows the user to
+		discover and change the online state of a CPU. To discover
+		the state:

This is present even without CONFIG_HOTPLUG_CPU.

Quoted 14 lines
Documentation/ABI/testing/sysfs-devices-cpu new file +13 -0
+
+		cat /sys/devices/system/cpu/$cpu/online
+
+		A value of 0 indicates the CPU is offline. A value of 1
+		indicates it is online. To change the state, echo the
+		desired new state into the file:
+
+		echo [0|1] > /sys/devices/system/cpu/$cpu/online
+
+		For more information, please read Documentation/cpu-hotplug.txt
+
+
+What:		/sys/devices/system/cpu/$cpu/node

Documentation/ABI/testing/sysfs-devices-cpu line 42

Quoted 10 lines
Documentation/ABI/testing/sysfs-devices-cpu new file +10 -0
+Date:		October 2009
+Contact:	Linux memory management mailing list <[email protected]>
+Description:
+		When CONFIG_NUMA is enabled, a symbolic link that points
+		to the corresponding NUMA node directory.
+
+		For example, the following symlink is created for cpu42
+		in NUMA node 2:
+
+		/sys/devices/system/cpu/cpu42/node2 -> ../../node/node2

Would it be possible for you to document all entities in /sys/devices/system/cpu/* in this new file (requiring a folding of Documentation/ABI/testing/sysfs-devices-cache_disable into it)?

#13 lore raw

Re: [PATCH 5/5] Documentation: ABI: document /sys/devices/system/cpu/

* David Rientjes <[email protected]>:

Quoted 10 lines · Alex Chiang

Documentation/ABI/testing/sysfs-devices-cpu

Quoted 6 lines
Documentation/ABI/testing/sysfs-devices-cpu new file +0 -0
new file mode 100644
index 0000000..9070889

Shouldn't this be called sysfs-devices-system-cpu?

Quoted 4 lines

I see what you're doing: /sys/devices/system/node/* files are contained in sysfs-devices-memory, but I think it would be helpful to have a more strict naming scheme so that the contents of a sysfs directory are described by a file of the same name.

Yeah, I was just trying to follow an earlier example. But you're right, since I'm creating a brand new file, I can do it the Right Way (tm).

Quoted 8 lines
Quoted 8 lines
Documentation/ABI/testing/sysfs-devices-cpu new file +7 -0
@@ -0,0 +1,42 @@
+What:		/sys/devices/system/cpu/
+Date:		October 2009
+Contact:	Linux kernel mailing list <[email protected]>
+Description:
+		A collection of CPU attributes, including cache information,
+		topology, and frequency. It also contains a mechanism to
+		logically hotplug CPUs.
Quoted 8 lines

Documentation/ABI/testing/sysfs-devices-cpu line 13

Quoted 6 lines
Documentation/ABI/testing/sysfs-devices-cpu new file +6 -0
+
+		The actual attributes present are architecture and
+		configuration dependent.
+
+
+What:		/sys/devices/system/cpu/$cpu/online

cpu# ?

Sure, will change (depending on response to my earlier email).

Quoted 8 lines

Documentation/ABI/testing/sysfs-devices-cpu line 19

Quoted 6 lines
Documentation/ABI/testing/sysfs-devices-cpu new file +6 -0
+Date:		January 2006
+Contact:	Linux kernel mailing list <[email protected]>
+Description:
+		When CONFIG_HOTPLUG_CPU is enabled, allows the user to
+		discover and change the online state of a CPU. To discover
+		the state:

This is present even without CONFIG_HOTPLUG_CPU.

That's what I get for not checking. Thank you for correcting me.

Quoted 21 lines
Quoted 21 lines
Documentation/ABI/testing/sysfs-devices-cpu new file +21 -0
+
+		cat /sys/devices/system/cpu/$cpu/online
+
+		A value of 0 indicates the CPU is offline. A value of 1
+		indicates it is online. To change the state, echo the
+		desired new state into the file:
+
+		echo [0|1] > /sys/devices/system/cpu/$cpu/online
+
+		For more information, please read Documentation/cpu-hotplug.txt
+
+
+What:		/sys/devices/system/cpu/$cpu/node
+Date:		October 2009
+Contact:	Linux memory management mailing list <[email protected]>
+Description:
+		When CONFIG_NUMA is enabled, a symbolic link that points
+		to the corresponding NUMA node directory.
+
+		For example, the following symlink is created for cpu42
+		in NUMA node 2:
Quoted 8 lines

Documentation/ABI/testing/sysfs-devices-cpu line 42

Quoted 3 lines
Documentation/ABI/testing/sysfs-devices-cpu new file +2 -0
+
+		/sys/devices/system/cpu/cpu42/node2 -> ../../node/node2

Would it be possible for you to document all entities in /sys/devices/system/cpu/* in this new file (requiring a folding of Documentation/ABI/testing/sysfs-devices-cache_disable into it)?

I'll give it a go. There are quite a few things in that directory though, like topology information, frequency, etc. that I wasn't so excited about documenting.

But if that's the tax to create my new symlinks, I'll pay it. ;)

Thanks for the review,
/ac

#14 lore raw

Re: [PATCH 5/5] Documentation: ABI: document /sys/devices/system/cpu/

Quoted 8 lines · Alex Chiang
Quoted 3 lines

Would it be possible for you to document all entities in /sys/devices/system/cpu/* in this new file (requiring a folding of Documentation/ABI/testing/sysfs-devices-cache_disable into it)?

I'll give it a go. There are quite a few things in that directory though, like topology information, frequency, etc. that I wasn't so excited about documenting.

Those are usually the ones where documentation is the most valuable and I'm sure would be greatly appreciated.

Quoted 2 lines

But if that's the tax to create my new symlinks, I'll pay it. ;)

It's definitely not required, I just thought it was a good opportunity to document all the contents under /sys/devices/system/cpu if you're going to do some of them. It's up to you.