mm: accurately document nr_free_*_pages functions with code comments

PATCH Superseded Zhang Yanfei 3 participants 5 messages Feb 6, 2013 – Feb 7, 2013

Subsystems (2)

Memory management Page allocator

lore

Share & tools

lore

Zhang Yanfei

author

2013-02-06 09:00 UTC #0 lore raw

PATCH 1/1 mm: accurately document nr_free_*_pages functions with code comments

Functions nr_free_zone_pages, nr_free_buffer_pages and nr_free_pagecache_pages are horribly badly named, so accurately document them with code comments in case of the misuse of them.

Signed-off-by Zhang Yanfei <[email protected]>

---
 mm/page_alloc.c |   23 +++++++++++++++++++----
 1 files changed, 19 insertions(+), 4 deletions(-)

mm/page_alloc.c +19 -4

index df2022f..0790716 100644
@@ -2785,6 +2785,15 @@ void free_pages_exact(void *virt, size_t size)
 }
 EXPORT_SYMBOL(free_pages_exact);
 
+/**
+ * nr_free_zone_pages - get pages that is beyond high watermark
+ * @offset - The zone index of the highest zone
+ *
+ * The function counts pages which are beyond high watermark within
+ * all zones at or below a given zone index. For each zone, the
+ * amount of pages is calculated as:
+ *     present_pages - high_pages
+ */
 static unsigned int nr_free_zone_pages(int offset)
 {
 	struct zoneref *z;

@@ -2805,8 +2814,11 @@ static unsigned int nr_free_zone_pages(int offset)
 	return sum;
 }
 
-/*
- * Amount of free RAM allocatable within ZONE_DMA and ZONE_NORMAL
+/**
+ * nr_free_buffer_pages - get pages that is beyond high watermark
+ *
+ * The function counts pages which are beyond high watermark within
+ * ZONE_DMA and ZONE_NORMAL.
  */
 unsigned int nr_free_buffer_pages(void)
 {

@@ -2814,8 +2826,11 @@ unsigned int nr_free_buffer_pages(void)
 }
 EXPORT_SYMBOL_GPL(nr_free_buffer_pages);
 
-/*
- * Amount of free RAM allocatable within all zones
+/**
+ * nr_free_pagecache_pages - get pages that is beyond high watermark
+ *
+ * The function counts pages which are beyond high watermark within
+ * all zones.
  */
 unsigned int nr_free_pagecache_pages(void)
 {

Signature · 7 lines

1.7.1

--
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>

Randy Dunlap

2013-02-07 00:55 UTC #1 lore raw

Quoted 14 lines · Zhang Yanfei

Functions nr_free_zone_pages, nr_free_buffer_pages and nr_free_pagecache_pages are horribly badly named, so accurately document them with code comments in case of the misuse of them.
Signed-off-by Zhang Yanfei <[email protected]>
---
 mm/page_alloc.c |   23 +++++++++++++++++++----
 1 files changed, 19 insertions(+), 4 deletions(-)
mm/page_alloc.c +0 -0
index df2022f..0790716 100644

mm/page_alloc.c void free_pages_exact(void *virt, size_t size) · line 2790

Quoted 6 lines

mm/page_alloc.c +3 -0

@@ -2785,6 +2785,15 @@ void free_pages_exact(void *virt, size_t size)
 }
 EXPORT_SYMBOL(free_pages_exact);
 
+/**
+ * nr_free_zone_pages - get pages that is beyond high watermark
+ * @offset - The zone index of the highest zone

Function parameter format uses a ':', not a '-'. E.g.,

* @offset: the zone index of the highest zone

Quoted 38 lines

mm/page_alloc.c +16 -4

+ *
+ * The function counts pages which are beyond high watermark within
+ * all zones at or below a given zone index. For each zone, the
+ * amount of pages is calculated as:
+ *     present_pages - high_pages
+ */
 static unsigned int nr_free_zone_pages(int offset)
 {
 	struct zoneref *z;

@@ -2805,8 +2814,11 @@ static unsigned int nr_free_zone_pages(int offset)
 	return sum;
 }
 
-/*
- * Amount of free RAM allocatable within ZONE_DMA and ZONE_NORMAL
+/**
+ * nr_free_buffer_pages - get pages that is beyond high watermark
+ *
+ * The function counts pages which are beyond high watermark within
+ * ZONE_DMA and ZONE_NORMAL.
  */
 unsigned int nr_free_buffer_pages(void)
 {

@@ -2814,8 +2826,11 @@ unsigned int nr_free_buffer_pages(void)
 }
 EXPORT_SYMBOL_GPL(nr_free_buffer_pages);
 
-/*
- * Amount of free RAM allocatable within all zones
+/**
+ * nr_free_pagecache_pages - get pages that is beyond high watermark
+ *
+ * The function counts pages which are beyond high watermark within
+ * all zones.
  */
 unsigned int nr_free_pagecache_pages(void)
 {

Signature · 7 lines

~Randy

--
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>

Zhang Yanfei

author

2013-02-07 01:55 UTC #2 lore raw

Quoted 18 lines · Randy Dunlap

Quoted 17 lines · Zhang Yanfei
Functions nr_free_zone_pages, nr_free_buffer_pages and nr_free_pagecache_pages are horribly badly named, so accurately document them with code comments in case of the misuse of them.
Signed-off-by Zhang Yanfei <[email protected]>
---
 mm/page_alloc.c |   23 +++++++++++++++++++----
 1 files changed, 19 insertions(+), 4 deletions(-)
mm/page_alloc.c +0 -0
index df2022f..0790716 100644
@@ -2785,6 +2785,15 @@ void free_pages_exact(void *virt, size_t size)
 }
 EXPORT_SYMBOL(free_pages_exact);
 

Quoted 7 lines

mm/page_alloc.c void free_pages_exact(void *virt, size_t size) · line 2790
Quoted 3 lines
mm/page_alloc.c +3 -0
+/**
+ * nr_free_zone_pages - get pages that is beyond high watermark
+ * @offset - The zone index of the highest zone
Function parameter format uses a ':', not a '-'. E.g.,
* @offset: the zone index of the highest zone

Sorry for my mistake. Thanks for your review.

Quoted 29 lines

mm/page_alloc.c +11 -2

+ *
+ * The function counts pages which are beyond high watermark within
+ * all zones at or below a given zone index. For each zone, the
+ * amount of pages is calculated as:
+ *     present_pages - high_pages
+ */
 static unsigned int nr_free_zone_pages(int offset)
 {
 	struct zoneref *z;

@@ -2805,8 +2814,11 @@ static unsigned int nr_free_zone_pages(int offset)
 	return sum;
 }
 
-/*
- * Amount of free RAM allocatable within ZONE_DMA and ZONE_NORMAL
+/**
+ * nr_free_buffer_pages - get pages that is beyond high watermark
+ *
+ * The function counts pages which are beyond high watermark within
+ * ZONE_DMA and ZONE_NORMAL.
  */
 unsigned int nr_free_buffer_pages(void)
 {

@@ -2814,8 +2826,11 @@ unsigned int nr_free_buffer_pages(void)
 }
 EXPORT_SYMBOL_GPL(nr_free_buffer_pages);

Quoted 13 lines

mm/page_alloc.c unsigned int nr_free_buffer_pages(void) · line 2836

Quoted 11 lines

mm/page_alloc.c +5 -2

-/*
- * Amount of free RAM allocatable within all zones
+/**
+ * nr_free_pagecache_pages - get pages that is beyond high watermark
+ *
+ * The function counts pages which are beyond high watermark within
+ * all zones.
  */
 unsigned int nr_free_pagecache_pages(void)
 {

--
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>

Zhang Yanfei

author

2013-02-07 01:59 UTC #3 lore raw

PATCH RESEND 1/1 mm: accurately document nr_free_*_pages functions with code comments

In reply to Randy Dunlap

Functions nr_free_zone_pages, nr_free_buffer_pages and nr_free_pagecache_pages are horribly badly named, so accurately document them with code comments in case of the misuse of them.

Reviewed-by Randy Dunlap <[email protected]>

Signed-off-by Zhang Yanfei <[email protected]>

---
 mm/page_alloc.c |   23 +++++++++++++++++++----
 1 files changed, 19 insertions(+), 4 deletions(-)

mm/page_alloc.c +19 -4

index df2022f..0790716 100644
@@ -2785,6 +2785,15 @@ void free_pages_exact(void *virt, size_t size)
 }
 EXPORT_SYMBOL(free_pages_exact);
 
+/**
+ * nr_free_zone_pages - get pages that is beyond high watermark
+ * @offset: The zone index of the highest zone
+ *
+ * The function counts pages which are beyond high watermark within
+ * all zones at or below a given zone index. For each zone, the
+ * amount of pages is calculated as:
+ *     present_pages - high_pages
+ */
 static unsigned int nr_free_zone_pages(int offset)
 {
 	struct zoneref *z;

@@ -2805,8 +2814,11 @@ static unsigned int nr_free_zone_pages(int offset)
 	return sum;
 }
 
-/*
- * Amount of free RAM allocatable within ZONE_DMA and ZONE_NORMAL
+/**
+ * nr_free_buffer_pages - get pages that is beyond high watermark
+ *
+ * The function counts pages which are beyond high watermark within
+ * ZONE_DMA and ZONE_NORMAL.
  */
 unsigned int nr_free_buffer_pages(void)
 {

@@ -2814,8 +2826,11 @@ unsigned int nr_free_buffer_pages(void)
 }
 EXPORT_SYMBOL_GPL(nr_free_buffer_pages);
 
-/*
- * Amount of free RAM allocatable within all zones
+/**
+ * nr_free_pagecache_pages - get pages that is beyond high watermark
+ *
+ * The function counts pages which are beyond high watermark within
+ * all zones.
  */
 unsigned int nr_free_pagecache_pages(void)
 {

Signature · 7 lines

1.7.1

--
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>

Andrew Morton

maintainer

2013-02-07 23:26 UTC #4 lore raw

Quoted 3 lines · On Thu, 07 Feb 2013 09:57:27 +0800 Zhang Yanfei <[email protected]>…

Functions nr_free_zone_pages, nr_free_buffer_pages and nr_free_pagecache_pages are horribly badly named, so accurately document them with code comments in case of the misuse of them.

Looks OK. I fiddled with it a bit:

mm/page_alloc.c renamed from mm/page_alloc.c~mm-accurately-document-nr_free__pages-functions-with-code-comments-fix +10 ~~-10~~

@@ -2813,12 +2813,12 @@ void free_pages_exact(void *virt, size_t
 EXPORT_SYMBOL(free_pages_exact);
 
 /**
- * nr_free_zone_pages - get pages that is beyond high watermark
+ * nr_free_zone_pages - count number of pages beyond high watermark
  * @offset: The zone index of the highest zone
  *
- * The function counts pages which are beyond high watermark within
- * all zones at or below a given zone index. For each zone, the
- * amount of pages is calculated as:
+ * nr_free_zone_pages() counts the number of counts pages which are beyond the
+ * high watermark within all zones at or below a given zone index.  For each
+ * zone, the number of pages is calculated as:
  *     present_pages - high_pages
  */
 static unsigned long nr_free_zone_pages(int offset)

@@ -2842,10 +2842,10 @@ static unsigned long nr_free_zone_pages(
 }
 
 /**
- * nr_free_buffer_pages - get pages that is beyond high watermark
+ * nr_free_buffer_pages - count number of pages beyond high watermark
  *
- * The function counts pages which are beyond high watermark within
- * ZONE_DMA and ZONE_NORMAL.
+ * nr_free_buffer_pages() counts the number of pages which are beyond the high
+ * watermark within ZONE_DMA and ZONE_NORMAL.
  */
 unsigned long nr_free_buffer_pages(void)
 {

@@ -2854,10 +2854,10 @@ unsigned long nr_free_buffer_pages(void)
 EXPORT_SYMBOL_GPL(nr_free_buffer_pages);
 
 /**
- * nr_free_pagecache_pages - get pages that is beyond high watermark
+ * nr_free_pagecache_pages - count number of pages beyond high watermark
  *
- * The function counts pages which are beyond high watermark within
- * all zones.
+ * nr_free_pagecache_pages() counts the number of pages which are beyond the
+ * high watermark within all zones.
  */
 unsigned long nr_free_pagecache_pages(void)
 {