Skip to contentSkip to conversation

mm: fix ambiguous comments for better code readability

PATCH Superseded [email protected] 2 participants 4 messages Feb 29, 2020 – Mar 1, 2020

Subsystems (2)
Memory management MM core

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore

[email protected]

author
#0 lore raw

PATCH 1/1 mm: fix ambiguous comments for better code readability

From: chenqiwu <[email protected]>

The parameter of remap_pfn_range() @pfn passed from the caller is actually a page-frame number converted by corresponding physical address of kernel memory, the original comment is ambiguous that may mislead the users.

Meanwhile, there is an ambiguous typo "VMM" in the comment of vm_area_struct. So fixing them will make the code more readable.

Signed-off-by chenqiwu <[email protected]>
---
 include/linux/mm_types.h | 4 ++--
 mm/memory.c              | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)
include/linux/mm_types.h +2 -2
index dd555e6..4aba6c0 100644
@@ -289,8 +289,8 @@ struct vm_userfaultfd_ctx {
 #endif /* CONFIG_USERFAULTFD */
 
 /*
- * This struct defines a memory VMM memory area. There is one of these
- * per VM-area/task.  A VM area is any part of the process virtual memory
+ * This struct describes a virtual memory area. There is one of these
+ * per VM-area/task. A VM area is any part of the process virtual memory
  * space that has a special rule for the page-fault handlers (ie a shared
  * library, the executable area etc).
  */
mm/memory.c +2 -2
index ce4b2b9..778aa00 100644
@@ -1948,8 +1948,8 @@ static inline int remap_p4d_range(struct mm_struct *mm, pgd_t *pgd,
  * remap_pfn_range - remap kernel memory to userspace
  * @vma: user vma to map to
  * @addr: target user address to start at
- * @pfn: physical address of kernel memory
- * @size: size of map area
+ * @pfn: remap pfn converted by physical address of kernel memory
+ * @size: size of mapping area
  * @prot: page protection flags for this mapping
  *
  * Note: this is only safe if the mm semaphore is held when called.
Signature · 1 line
1.9.1
#1 lore raw

mm/memory.c static inline int remap_p4d_range(struct mm_struct *mm, pgd_t *pgd, · line 1951

Quoted 8 lines · On Sat, Feb 29, 2020 at 11:25:49PM +0800, [email protected] wrote:

+++ b/mm/memory.c

mm/memory.c +1 -2
@@ -1948,8 +1948,8 @@ static inline int remap_p4d_range(struct mm_struct *mm, pgd_t *pgd,
  * remap_pfn_range - remap kernel memory to userspace
  * @vma: user vma to map to
  * @addr: target user address to start at
- * @pfn: physical address of kernel memory
- * @size: size of map area
+ * @pfn: remap pfn converted by physical address of kernel memory

I think that's actually worse. How about:

* @pfn: Page Frame Number of memory.

author
#2 lore raw
Quoted 12 lines · Matthew Wilcox

mm/memory.c static inline int remap_p4d_range(struct mm_struct *mm, pgd_t *pgd, · line 1951

Quoted 8 lines · On Sat, Feb 29, 2020 at 11:25:49PM +0800, [email protected] wrote:

+++ b/mm/memory.c

mm/memory.c +1 -2
@@ -1948,8 +1948,8 @@ static inline int remap_p4d_range(struct mm_struct *mm, pgd_t *pgd,
  * remap_pfn_range - remap kernel memory to userspace
  * @vma: user vma to map to
  * @addr: target user address to start at
- * @pfn: physical address of kernel memory
- * @size: size of map area
+ * @pfn: remap pfn converted by physical address of kernel memory

I think that's actually worse. How about:

Quoted 1 line

* @pfn: Page Frame Number of memory.

Hmm... I think "Page Frame Number of kernel memory" should be better.

Quoted 1 line
#3 lore raw
Quoted 13 lines · chenqiwu
Quoted 12 lines · Matthew Wilcox

mm/memory.c static inline int remap_p4d_range(struct mm_struct *mm, pgd_t *pgd, · line 1951

Quoted 8 lines · On Sat, Feb 29, 2020 at 11:25:49PM +0800, [email protected] wrote:

+++ b/mm/memory.c

mm/memory.c +1 -2
@@ -1948,8 +1948,8 @@ static inline int remap_p4d_range(struct mm_struct *mm, pgd_t *pgd,
  * remap_pfn_range - remap kernel memory to userspace
  * @vma: user vma to map to
  * @addr: target user address to start at
- * @pfn: physical address of kernel memory
- * @size: size of map area
+ * @pfn: remap pfn converted by physical address of kernel memory

I think that's actually worse. How about:

Quoted 3 lines
Quoted 1 line

* @pfn: Page Frame Number of memory.

Hmm... I think "Page Frame Number of kernel memory" should be better.

I disagree. We already know the memory is kernel memory from the first line. Repeating this information in the parameter description isn't particularly helpful.