Skip to contentSkip to conversation

mm/sparse: Clean up the obsolete code comment

PATCH Superseded Baoquan He 5 participants 14 messages Mar 29, 2019 – Mar 30, 2019

Subsystems (4)

v3 of 4 Superseded Latest is v4 →

lore
Share & tools
lore

Baoquan He

author
#0 lore raw

PATCH v3 1/2 mm/sparse: Clean up the obsolete code comment

The code comment above sparse_add_one_section() is obsolete and incorrect, clean it up and write new one.

---
v2->v3:
Normalize the code comment to use '/**' at 1st line of doc above function.
v1-v2:
Add comments to explain what the returned value means for each error code.

 mm/sparse.c | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)
mm/sparse.c +13 -4
index 69904aa6165b..363f9d31b511 100644
@@ -684,10 +684,19 @@ static void free_map_bootmem(struct page *memmap)
 #endif /* CONFIG_MEMORY_HOTREMOVE */
 #endif /* CONFIG_SPARSEMEM_VMEMMAP */
 
-/*
- * returns the number of sections whose mem_maps were properly
- * set.  If this is <=0, then that means that the passed-in
- * map was not consumed and must be freed.
+/**
+ * sparse_add_one_section - add a memory section
+ * @nid: The node to add section on
+ * @start_pfn: start pfn of the memory range
+ * @altmap: device page map
+ *
+ * This is only intended for hotplug.
+ *
+ * Returns:
+ *   0 on success.
+ *   Other error code on failure:
+ *     - -EEXIST - section has been present.
+ *     - -ENOMEM - out of memory.
  */
 int __meminit sparse_add_one_section(int nid, unsigned long start_pfn,
 				     struct vmem_altmap *altmap)
Signature · 1 line
2.17.2
author
#1 lore raw

PATCH v3 2/2 drivers/base/memory.c: Rename the misleading parameter

The input parameter 'phys_index' of memory_block_action() is actually the section number, but not the phys_index of memory_block. Fix it.

---
v2->v3:
Rename the parameter to 'start_section_nr' from 'sec'.

 drivers/base/memory.c | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
drivers/base/memory.c +4 -3
index cb8347500ce2..9ea972b2ae79 100644
@@ -231,13 +231,14 @@ static bool pages_correctly_probed(unsigned long start_pfn)
  * OK to have direct references to sparsemem variables in here.
  */
 static int
-memory_block_action(unsigned long phys_index, unsigned long action, int online_type)
+memory_block_action(unsigned long start_section_nr, unsigned long action,
+		    int online_type)
 {
 	unsigned long start_pfn;
 	unsigned long nr_pages = PAGES_PER_SECTION * sections_per_block;
 	int ret;
 
-	start_pfn = section_nr_to_pfn(phys_index);
+	start_pfn = section_nr_to_pfn(start_section_nr);
 
 	switch (action) {
 	case MEM_ONLINE:
@@ -251,7 +252,7 @@ memory_block_action(unsigned long phys_index, unsigned long action, int online_t
 		break;
 	default:
 		WARN(1, KERN_WARNING "%s(%ld, %ld) unknown action: "
-		     "%ld\n", __func__, phys_index, action, action);
+		     "%ld\n", __func__, start_section_nr, action, action);
 		ret = -EINVAL;
 	}
 
Signature · 1 line
2.17.2
#2 lore raw

Re: [PATCH v3 2/2] drivers/base/memory.c: Rename the misleading parameter

Quoted 2 lines · Baoquan He

The input parameter 'phys_index' of memory_block_action() is actually the section number, but not the phys_index of memory_block. Fix it.

I have tried to explain that the naming is mostly a relict from the past
than really a misleading name http://lkml.kernel.org/r/[email protected]
Maybe it would be good to reflect that in the changelog

Quoted 1 line

btw. I've acked the previous version as well.

Quoted 40 lines

---
v2->v3:
Rename the parameter to 'start_section_nr' from 'sec'.

 drivers/base/memory.c | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
drivers/base/memory.c +4 -3
index cb8347500ce2..9ea972b2ae79 100644
@@ -231,13 +231,14 @@ static bool pages_correctly_probed(unsigned long start_pfn)
  * OK to have direct references to sparsemem variables in here.
  */
 static int
-memory_block_action(unsigned long phys_index, unsigned long action, int online_type)
+memory_block_action(unsigned long start_section_nr, unsigned long action,
+		    int online_type)
 {
 	unsigned long start_pfn;
 	unsigned long nr_pages = PAGES_PER_SECTION * sections_per_block;
 	int ret;
 
-	start_pfn = section_nr_to_pfn(phys_index);
+	start_pfn = section_nr_to_pfn(start_section_nr);
 
 	switch (action) {
 	case MEM_ONLINE:
@@ -251,7 +252,7 @@ memory_block_action(unsigned long phys_index, unsigned long action, int online_t
 		break;
 	default:
 		WARN(1, KERN_WARNING "%s(%ld, %ld) unknown action: "
-		     "%ld\n", __func__, phys_index, action, action);
+		     "%ld\n", __func__, start_section_nr, action, action);
 		ret = -EINVAL;
 	}
 
Signature · 1 line
2.17.2
Signature · 2 lines
Michal Hocko
SUSE Labs
author
#3 lore raw

Re: [PATCH v3 2/2] drivers/base/memory.c: Rename the misleading parameter

Quoted 11 lines · Michal Hocko
Quoted 2 lines · Baoquan He

The input parameter 'phys_index' of memory_block_action() is actually the section number, but not the phys_index of memory_block. Fix it.

I have tried to explain that the naming is mostly a relict from the past
than really a misleading name http://lkml.kernel.org/r/[email protected]
Maybe it would be good to reflect that in the changelog

Quoted 1 line

btw. I've acked the previous version as well.

Sure, will rewrite the log and add people's Acked-by tag. Thanks.

Quoted 45 lines
Quoted 41 lines

---
v2->v3:
Rename the parameter to 'start_section_nr' from 'sec'.

 drivers/base/memory.c | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
drivers/base/memory.c +4 -3
index cb8347500ce2..9ea972b2ae79 100644
@@ -231,13 +231,14 @@ static bool pages_correctly_probed(unsigned long start_pfn)
  * OK to have direct references to sparsemem variables in here.
  */
 static int
-memory_block_action(unsigned long phys_index, unsigned long action, int online_type)
+memory_block_action(unsigned long start_section_nr, unsigned long action,
+		    int online_type)
 {
 	unsigned long start_pfn;
 	unsigned long nr_pages = PAGES_PER_SECTION * sections_per_block;
 	int ret;
 
-	start_pfn = section_nr_to_pfn(phys_index);
+	start_pfn = section_nr_to_pfn(start_section_nr);
 
 	switch (action) {
 	case MEM_ONLINE:
@@ -251,7 +252,7 @@ memory_block_action(unsigned long phys_index, unsigned long action, int online_t
 		break;
 	default:
 		WARN(1, KERN_WARNING "%s(%ld, %ld) unknown action: "
-		     "%ld\n", __func__, phys_index, action, action);
+		     "%ld\n", __func__, start_section_nr, action, action);
 		ret = -EINVAL;
 	}
 
Signature · 1 line
2.17.2
Signature · 2 lines
Michal Hocko
SUSE Labs
maintainer
#4 lore raw

Re: [PATCH v3 2/2] drivers/base/memory.c: Rename the misleading parameter

In reply to Michal Hocko
Quoted 7 lines · Michal Hocko
Quoted 2 lines · Baoquan He

The input parameter 'phys_index' of memory_block_action() is actually the section number, but not the phys_index of memory_block. Fix it.

I have tried to explain that the naming is mostly a relict from the past
than really a misleading name http://lkml.kernel.org/r/[email protected]
Maybe it would be good to reflect that in the changelog

I think that phys_device variable in remove_memory_section() is also a relict from the past, and it is no longer used.
Neither node_id variable is used.
Actually, unregister_memory_section() sets those two to 0 no matter what.

Since we are cleaning up, I wonder if we can go a bit further and we can get rid of that as well.

Signature · 2 lines
Oscar Salvador
SUSE L3
author
#5 lore raw

Re: [PATCH v3 2/2] drivers/base/memory.c: Rename the misleading parameter

Quoted 9 lines · Oscar Salvador
Quoted 7 lines · Michal Hocko
Quoted 2 lines · Baoquan He

The input parameter 'phys_index' of memory_block_action() is actually the section number, but not the phys_index of memory_block. Fix it.

I have tried to explain that the naming is mostly a relict from the past
than really a misleading name http://lkml.kernel.org/r/[email protected]
Maybe it would be good to reflect that in the changelog

Quoted 7 lines

I think that phys_device variable in remove_memory_section() is also a relict from the past, and it is no longer used.
Neither node_id variable is used.
Actually, unregister_memory_section() sets those two to 0 no matter what.

Since we are cleaning up, I wonder if we can go a bit further and we can get rid of that as well.

Yes, certainly. I would like to post a new one to carry this.

author
#6 lore raw

PATCH v4 2/2 drivers/base/memory.c: Rename the misleading parameter

In reply to Baoquan He

The input parameter 'phys_index' of memory_block_action() is actually the section number, but not the phys_index of memory_block. This is a relict from the past when one memory block could only contain one section.

Rename it to start_section_nr.

---
 drivers/base/memory.c | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
drivers/base/memory.c +4 -3
index cb8347500ce2..9ea972b2ae79 100644
@@ -231,13 +231,14 @@ static bool pages_correctly_probed(unsigned long start_pfn)
  * OK to have direct references to sparsemem variables in here.
  */
 static int
-memory_block_action(unsigned long phys_index, unsigned long action, int online_type)
+memory_block_action(unsigned long start_section_nr, unsigned long action,
+		    int online_type)
 {
 	unsigned long start_pfn;
 	unsigned long nr_pages = PAGES_PER_SECTION * sections_per_block;
 	int ret;
 
-	start_pfn = section_nr_to_pfn(phys_index);
+	start_pfn = section_nr_to_pfn(start_section_nr);
 
 	switch (action) {
 	case MEM_ONLINE:
@@ -251,7 +252,7 @@ memory_block_action(unsigned long phys_index, unsigned long action, int online_t
 		break;
 	default:
 		WARN(1, KERN_WARNING "%s(%ld, %ld) unknown action: "
-		     "%ld\n", __func__, phys_index, action, action);
+		     "%ld\n", __func__, start_section_nr, action, action);
 		ret = -EINVAL;
 	}
 
Signature · 1 line
2.17.2
maintainer Reviewed-by on v4 2/2
#7 lore raw

Re: [PATCH v4 2/2] drivers/base/memory.c: Rename the misleading parameter

Quoted 10 lines · Baoquan He

The input parameter 'phys_index' of memory_block_action() is actually the section number, but not the phys_index of memory_block. This is a relict from the past when one memory block could only contain one section.

Rename it to start_section_nr.

Quoted 37 lines
---
 drivers/base/memory.c | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
drivers/base/memory.c +4 -3
index cb8347500ce2..9ea972b2ae79 100644
@@ -231,13 +231,14 @@ static bool pages_correctly_probed(unsigned long start_pfn)
  * OK to have direct references to sparsemem variables in here.
  */
 static int
-memory_block_action(unsigned long phys_index, unsigned long action, int online_type)
+memory_block_action(unsigned long start_section_nr, unsigned long action,
+		    int online_type)
 {
 	unsigned long start_pfn;
 	unsigned long nr_pages = PAGES_PER_SECTION * sections_per_block;
 	int ret;
 
-	start_pfn = section_nr_to_pfn(phys_index);
+	start_pfn = section_nr_to_pfn(start_section_nr);
 
 	switch (action) {
 	case MEM_ONLINE:
@@ -251,7 +252,7 @@ memory_block_action(unsigned long phys_index, unsigned long action, int online_t
 		break;
 	default:
 		WARN(1, KERN_WARNING "%s(%ld, %ld) unknown action: "
-		     "%ld\n", __func__, phys_index, action, action);
+		     "%ld\n", __func__, start_section_nr, action, action);
 		ret = -EINVAL;
 	}
 
Signature · 1 line
2.17.2
Signature · 2 lines
Oscar Salvador
SUSE L3
Reviewed-by on v4 2/2
#8 lore raw

Re: [PATCH v4 2/2] drivers/base/memory.c: Rename the misleading parameter

In reply to Baoquan He
Quoted 10 lines · Baoquan He

The input parameter 'phys_index' of memory_block_action() is actually the section number, but not the phys_index of memory_block. This is a relict from the past when one memory block could only contain one section.

Rename it to start_section_nr.

Cheers,
-Mukesh

Quoted 34 lines
---
  drivers/base/memory.c | 7 ++++---
  1 file changed, 4 insertions(+), 3 deletions(-)
drivers/base/memory.c +4 -3
index cb8347500ce2..9ea972b2ae79 100644
@@ -231,13 +231,14 @@ static bool pages_correctly_probed(unsigned long start_pfn)
   * OK to have direct references to sparsemem variables in here.
   */
  static int
-memory_block_action(unsigned long phys_index, unsigned long action, int online_type)
+memory_block_action(unsigned long start_section_nr, unsigned long action,
+		    int online_type)
  {
  	unsigned long start_pfn;
  	unsigned long nr_pages = PAGES_PER_SECTION * sections_per_block;
  	int ret;
 
-	start_pfn = section_nr_to_pfn(phys_index);
+	start_pfn = section_nr_to_pfn(start_section_nr);
 
  	switch (action) {
  	case MEM_ONLINE:
@@ -251,7 +252,7 @@ memory_block_action(unsigned long phys_index, unsigned long action, int online_t
  		break;
  	default:
  		WARN(1, KERN_WARNING "%s(%ld, %ld) unknown action: "
-		     "%ld\n", __func__, phys_index, action, action);
+		     "%ld\n", __func__, start_section_nr, action, action);
  		ret = -EINVAL;
  	}
 
Acked-by on v3 1/2
#9 lore raw
In reply to Baoquan He
Quoted 4 lines · Baoquan He

The code comment above sparse_add_one_section() is obsolete and incorrect, clean it up and write new one.

Quoted 41 lines

---
v2->v3:
Normalize the code comment to use '/**' at 1st line of doc above function.
v1-v2:
Add comments to explain what the returned value means for each error code.

 mm/sparse.c | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)
mm/sparse.c +13 -4
index 69904aa6165b..363f9d31b511 100644
@@ -684,10 +684,19 @@ static void free_map_bootmem(struct page *memmap)
 #endif /* CONFIG_MEMORY_HOTREMOVE */
 #endif /* CONFIG_SPARSEMEM_VMEMMAP */
 
-/*
- * returns the number of sections whose mem_maps were properly
- * set.  If this is <=0, then that means that the passed-in
- * map was not consumed and must be freed.
+/**
+ * sparse_add_one_section - add a memory section
+ * @nid: The node to add section on
+ * @start_pfn: start pfn of the memory range
+ * @altmap: device page map
+ *
+ * This is only intended for hotplug.
+ *
+ * Returns:
+ *   0 on success.
+ *   Other error code on failure:
+ *     - -EEXIST - section has been present.
+ *     - -ENOMEM - out of memory.
  */
 int __meminit sparse_add_one_section(int nid, unsigned long start_pfn,
 				     struct vmem_altmap *altmap)
Signature · 1 line
2.17.2
Signature · 2 lines
Michal Hocko
SUSE Labs
maintainer Reviewed-by on v3 1/2
#10 lore raw
In reply to Baoquan He
Quoted 4 lines · Baoquan He

The code comment above sparse_add_one_section() is obsolete and incorrect, clean it up and write new one.

Quoted 25 lines

---
v2->v3:
Normalize the code comment to use '/**' at 1st line of doc above function.
v1-v2:
Add comments to explain what the returned value means for each error code.

 mm/sparse.c | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)
mm/sparse.c +3 -4
index 69904aa6165b..363f9d31b511 100644
@@ -684,10 +684,19 @@ static void free_map_bootmem(struct page *memmap)
 #endif /* CONFIG_MEMORY_HOTREMOVE */
 #endif /* CONFIG_SPARSEMEM_VMEMMAP */
 
-/*
- * returns the number of sections whose mem_maps were properly
- * set.  If this is <=0, then that means that the passed-in
- * map was not consumed and must be freed.
+/**
+ * sparse_add_one_section - add a memory section
+ * @nid: The node to add section on

mm/sparse.c static void free_map_bootmem(struct page *memmap) · line 699

Quoted 10 lines
mm/sparse.c +10 -0
+ * @start_pfn: start pfn of the memory range
+ * @altmap: device page map
+ *
+ * This is only intended for hotplug.
+ *
+ * Returns:
+ *   0 on success.
+ *   Other error code on failure:
+ *     - -EEXIST - section has been present.
+ *     - -ENOMEM - out of memory.

I am not really into kernel-doc format, but I thought it was something like:

<--
Return:
0: success
-EEXIST: Section is already present
-ENOMEM: Out of memory
-->

But as I said, I might very well be wrong.

Signature · 2 lines
Oscar Salvador
SUSE L3
author
#11 lore raw
Quoted 16 lines · Oscar Salvador
Quoted 5 lines

+/**
+ * sparse_add_one_section - add a memory section
+ * @nid: The node to add section on
+ * @start_pfn: start pfn of the memory range
+ * @altmap: device page map

Quoted 8 lines

+ *
+ * This is only intended for hotplug.
+ *
+ * Returns:
+ * 0 on success.
+ * Other error code on failure:
+ * - -EEXIST - section has been present.
+ * - -ENOMEM - out of memory.

I am not really into kernel-doc format, but I thought it was something like:

Quoted 8 lines

<--
Return:
0: success
-EEXIST: Section is already present
-ENOMEM: Out of memory
-->

But as I said, I might very well be wrong.

Below is excerpt from doc-guide/kernel-doc.rst. Seems they suggest it like this if format returned values with multi-line style. While the format is not strictly defined. I will use it to update.

*Return:
* * 0 - Success
* * -EEXIST - Section is already present
* * -ENOMEM - Out of memory

The return value, if any, should be described in a dedicated section named ``Return``.

.. note::

#) The multi-line descriptive text you provide does *not* recognize
line breaks, so if you try to format some text nicely, as in::

* Return:
* 0 - OK
* -EINVAL - invalid argument
* -ENOMEM - out of memory

this will all run together and produce::

Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory

So, in order to produce the desired line breaks, you need to use a ReST list, e. g.::

* Return:
* * 0 - OK to runtime suspend the device
* * -EBUSY - Device should not be runtime suspended

Reviewed-by on v3 1/2
#12 lore raw
In reply to Baoquan He
Quoted 4 lines · Baoquan He

The code comment above sparse_add_one_section() is obsolete and incorrect, clean it up and write new one.

Cheers,
-Mukesh

Quoted 38 lines

---
v2->v3:
Normalize the code comment to use '/**' at 1st line of doc above function.
v1-v2:
Add comments to explain what the returned value means for each error code.

  mm/sparse.c | 17 +++++++++++++----
  1 file changed, 13 insertions(+), 4 deletions(-)
mm/sparse.c +13 -4
index 69904aa6165b..363f9d31b511 100644
@@ -684,10 +684,19 @@ static void free_map_bootmem(struct page *memmap)
  #endif /* CONFIG_MEMORY_HOTREMOVE */
  #endif /* CONFIG_SPARSEMEM_VMEMMAP */
 
-/*
- * returns the number of sections whose mem_maps were properly
- * set.  If this is <=0, then that means that the passed-in
- * map was not consumed and must be freed.
+/**
+ * sparse_add_one_section - add a memory section
+ * @nid: The node to add section on
+ * @start_pfn: start pfn of the memory range
+ * @altmap: device page map
+ *
+ * This is only intended for hotplug.
+ *
+ * Returns:
+ *   0 on success.
+ *   Other error code on failure:
+ *     - -EEXIST - section has been present.
+ *     - -ENOMEM - out of memory.
   */
  int __meminit sparse_add_one_section(int nid, unsigned long start_pfn,
  				     struct vmem_altmap *altmap)
Reviewed-by on v3 1/2
#13 lore raw
In reply to Baoquan He
Quoted 4 lines · Baoquan He

The code comment above sparse_add_one_section() is obsolete and incorrect, clean it up and write new one.

Quoted 41 lines

---
v2->v3:
Normalize the code comment to use '/**' at 1st line of doc above function.
v1-v2:
Add comments to explain what the returned value means for each error code.

 mm/sparse.c | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)
mm/sparse.c +13 -4
index 69904aa6165b..363f9d31b511 100644
@@ -684,10 +684,19 @@ static void free_map_bootmem(struct page *memmap)
 #endif /* CONFIG_MEMORY_HOTREMOVE */
 #endif /* CONFIG_SPARSEMEM_VMEMMAP */
 
-/*
- * returns the number of sections whose mem_maps were properly
- * set.  If this is <=0, then that means that the passed-in
- * map was not consumed and must be freed.
+/**
+ * sparse_add_one_section - add a memory section
+ * @nid: The node to add section on
+ * @start_pfn: start pfn of the memory range
+ * @altmap: device page map
+ *
+ * This is only intended for hotplug.
+ *
+ * Returns:
+ *   0 on success.
+ *   Other error code on failure:
+ *     - -EEXIST - section has been present.
+ *     - -ENOMEM - out of memory.
  */
 int __meminit sparse_add_one_section(int nid, unsigned long start_pfn,
 				     struct vmem_altmap *altmap)
Signature · 1 line
2.17.2
Signature · 2 lines
Sincerely yours,
Mike.