mm/sparse: Clean up the obsolete code comment
Subsystems (4)
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
@@ -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
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
@@ -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_tbreak ;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
Re: [PATCH v3 2/2] drivers/base/memory.c: Rename the misleading parameter
Quoted 2 lines · Baoquan He
The input parameter '
phys_index' ofmemory_block_action()is actually the section number, but not thephys_indexofmemory_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
Signed-off-by Baoquan He <[email protected]>
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@@ -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_tbreak ;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
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' ofmemory_block_action()is actually the section number, but not thephys_indexofmemory_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 changelogQuoted 1 line
Signed-off-by Baoquan He <[email protected]>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@@ -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_tbreak ;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.2Signature · 2 lines
Michal Hocko SUSE Labs
Oscar Salvador
maintainerRe: [PATCH v3 2/2] drivers/base/memory.c: Rename the misleading parameter
In reply to Michal HockoQuoted 7 lines · Michal Hocko
Quoted 2 lines · Baoquan He
The input parameter '
phys_index' ofmemory_block_action()is actually the section number, but not thephys_indexofmemory_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
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' ofmemory_block_action()is actually the section number, but not thephys_indexofmemory_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_devicevariable inremove_memory_section()is also a relict from the past, and it is no longer used.
Neithernode_idvariable 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.
PATCH v4 2/2 drivers/base/memory.c: Rename the misleading parameter
In reply to Baoquan HeThe 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
@@ -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_tbreak ;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
Re: [PATCH v4 2/2] drivers/base/memory.c: Rename the misleading parameter
Quoted 10 lines · Baoquan He
The input parameter '
phys_index' ofmemory_block_action()is actually the section number, but not thephys_indexofmemory_block. This is a relict from the past when one memory block could only contain one section.Rename it to
start_section_nr.Signed-off-by Baoquan He <[email protected]>Acked-by Michal Hocko <[email protected]>Reviewed-by Rafael J. Wysocki <[email protected]>
Quoted 37 lines
--- drivers/base/memory.c | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)drivers/base/memory.c +4
-3@@ -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_tbreak ;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
Re: [PATCH v4 2/2] drivers/base/memory.c: Rename the misleading parameter
In reply to Baoquan HeQuoted 10 lines · Baoquan He
The input parameter '
phys_index' ofmemory_block_action()is actually the section number, but not thephys_indexofmemory_block. This is a relict from the past when one memory block could only contain one section.Rename it to
start_section_nr.Signed-off-by Baoquan He <[email protected]>Acked-by Michal Hocko <[email protected]>Reviewed-by Rafael J. Wysocki <[email protected]>
Cheers,
-Mukesh
Quoted 34 lines
--- drivers/base/memory.c | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)drivers/base/memory.c +4
-3@@ -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_tbreak ;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 ; }
Quoted 4 lines · Baoquan He
The code comment above
sparse_add_one_section()is obsolete and incorrect, clean it up and write new one.Signed-off-by Baoquan He <[email protected]>
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@@ -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
Quoted 4 lines · Baoquan He
The code comment above
sparse_add_one_section()is obsolete and incorrect, clean it up and write new one.Signed-off-by Baoquan He <[email protected]>
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@@ -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
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 mapQuoted 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
Quoted 4 lines · Baoquan He
The code comment above
sparse_add_one_section()is obsolete and incorrect, clean it up and write new one.Signed-off-by Baoquan He <[email protected]>
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@@ -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)
Quoted 4 lines · Baoquan He
The code comment above
sparse_add_one_section()is obsolete and incorrect, clean it up and write new one.Signed-off-by Baoquan He <[email protected]>
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@@ -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.