* [PATCH v4 21/27] memblock: fix kernel-doc markups
2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 25/27] mm: " Mauro Carvalho Chehab
2020-11-17 22:19 ` [PATCH v4 00/27]Fix several bad " Jakub Kicinski
2 siblings, 0 replies; 4+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
To: Mike Rapoport
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List,
linux-kernel, linux-mm, Mike Rapoport
Some identifiers have different names between their prototypes
and the kernel-doc markup.
Acked-by: Mike Rapoport <rppt@linux.ibm.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
include/linux/memblock.h | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/include/linux/memblock.h b/include/linux/memblock.h
index ef131255cedc..95fe3cb71c54 100644
--- a/include/linux/memblock.h
+++ b/include/linux/memblock.h
@@ -255,61 +255,61 @@ void __next_mem_pfn_range(int *idx, int nid, unsigned long *out_start_pfn,
/**
* for_each_mem_pfn_range - early memory pfn range iterator
* @i: an integer used as loop variable
* @nid: node selector, %MAX_NUMNODES for all nodes
* @p_start: ptr to ulong for start pfn of the range, can be %NULL
* @p_end: ptr to ulong for end pfn of the range, can be %NULL
* @p_nid: ptr to int for nid of the range, can be %NULL
*
* Walks over configured memory ranges.
*/
#define for_each_mem_pfn_range(i, nid, p_start, p_end, p_nid) \
for (i = -1, __next_mem_pfn_range(&i, nid, p_start, p_end, p_nid); \
i >= 0; __next_mem_pfn_range(&i, nid, p_start, p_end, p_nid))
#ifdef CONFIG_DEFERRED_STRUCT_PAGE_INIT
void __next_mem_pfn_range_in_zone(u64 *idx, struct zone *zone,
unsigned long *out_spfn,
unsigned long *out_epfn);
/**
- * for_each_free_mem_range_in_zone - iterate through zone specific free
+ * for_each_free_mem_pfn_range_in_zone - iterate through zone specific free
* memblock areas
* @i: u64 used as loop variable
* @zone: zone in which all of the memory blocks reside
* @p_start: ptr to phys_addr_t for start address of the range, can be %NULL
* @p_end: ptr to phys_addr_t for end address of the range, can be %NULL
*
* Walks over free (memory && !reserved) areas of memblock in a specific
* zone. Available once memblock and an empty zone is initialized. The main
* assumption is that the zone start, end, and pgdat have been associated.
* This way we can use the zone to determine NUMA node, and if a given part
* of the memblock is valid for the zone.
*/
#define for_each_free_mem_pfn_range_in_zone(i, zone, p_start, p_end) \
for (i = 0, \
__next_mem_pfn_range_in_zone(&i, zone, p_start, p_end); \
i != U64_MAX; \
__next_mem_pfn_range_in_zone(&i, zone, p_start, p_end))
/**
- * for_each_free_mem_range_in_zone_from - iterate through zone specific
+ * for_each_free_mem_pfn_range_in_zone_from - iterate through zone specific
* free memblock areas from a given point
* @i: u64 used as loop variable
* @zone: zone in which all of the memory blocks reside
* @p_start: ptr to phys_addr_t for start address of the range, can be %NULL
* @p_end: ptr to phys_addr_t for end address of the range, can be %NULL
*
* Walks over free (memory && !reserved) areas of memblock in a specific
* zone, continuing from current position. Available as soon as memblock is
* initialized.
*/
#define for_each_free_mem_pfn_range_in_zone_from(i, zone, p_start, p_end) \
for (; i != U64_MAX; \
__next_mem_pfn_range_in_zone(&i, zone, p_start, p_end))
int __init deferred_page_init_max_threads(const struct cpumask *node_cpumask);
#endif /* CONFIG_DEFERRED_STRUCT_PAGE_INIT */
/**
* for_each_free_mem_range - iterate through free memblock areas
--
2.28.0
^ permalink raw reply related [flat|nested] 4+ messages in thread
* [PATCH v4 25/27] mm: fix kernel-doc markups
2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 21/27] memblock: fix " Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
2020-11-17 22:19 ` [PATCH v4 00/27]Fix several bad " Jakub Kicinski
2 siblings, 0 replies; 4+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
To: Andrew Morton
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List,
linux-kernel, linux-mm, Mattew Wilcox
Kernel-doc markups should use this format:
identifier - description
Fix some issues on mm files:
1) The definition for get_user_pages_locked() doesn't follow
it. Also, it expects a short descrpition at the header,
followed by a long one, after the parameters. Fix it.
2) Kernel-doc requires that a kernel-doc markup to be immediatly
below the function prototype, as otherwise it will rename it.
So, move get_pfnblock_flags_mask() description to the right
place.
3) Make invalidate_mapping_pagevec() to also follow the
expected kernel-doc format.
While here, fix a few minor English syntax issues, as suggested
by Matthew:
will used -> will be used
similar with -> similar to
Suggested-by: Mattew Wilcox <willy@infradead.org> # English fixes
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
mm/gup.c | 24 +++++++++++++-----------
mm/page_alloc.c | 16 ++++++++--------
mm/truncate.c | 10 ++++++++--
3 files changed, 29 insertions(+), 21 deletions(-)
diff --git a/mm/gup.c b/mm/gup.c
index 49c4eabca271..f3751bf28326 100644
--- a/mm/gup.c
+++ b/mm/gup.c
@@ -1924,66 +1924,68 @@ static long __get_user_pages_remote(struct mm_struct *mm,
* Or NULL if the caller does not require them.
*
* This is the same as get_user_pages_remote(), just with a less-flexible
* calling convention where we assume that the mm being operated on belongs to
* the current task, and doesn't allow passing of a locked parameter. We also
* obviously don't pass FOLL_REMOTE in here.
*/
long get_user_pages(unsigned long start, unsigned long nr_pages,
unsigned int gup_flags, struct page **pages,
struct vm_area_struct **vmas)
{
if (!is_valid_gup_flags(gup_flags))
return -EINVAL;
return __gup_longterm_locked(current->mm, start, nr_pages,
pages, vmas, gup_flags | FOLL_TOUCH);
}
EXPORT_SYMBOL(get_user_pages);
/**
- * get_user_pages_locked() is suitable to replace the form:
+ * get_user_pages_locked() - variant of get_user_pages()
+ *
+ * @start: starting user address
+ * @nr_pages: number of pages from start to pin
+ * @gup_flags: flags modifying lookup behaviour
+ * @pages: array that receives pointers to the pages pinned.
+ * Should be at least nr_pages long. Or NULL, if caller
+ * only intends to ensure the pages are faulted in.
+ * @locked: pointer to lock flag indicating whether lock is held and
+ * subsequently whether VM_FAULT_RETRY functionality can be
+ * utilised. Lock must initially be held.
+ *
+ * It is suitable to replace the form:
*
* mmap_read_lock(mm);
* do_something()
* get_user_pages(mm, ..., pages, NULL);
* mmap_read_unlock(mm);
*
* to:
*
* int locked = 1;
* mmap_read_lock(mm);
* do_something()
* get_user_pages_locked(mm, ..., pages, &locked);
* if (locked)
* mmap_read_unlock(mm);
*
- * @start: starting user address
- * @nr_pages: number of pages from start to pin
- * @gup_flags: flags modifying lookup behaviour
- * @pages: array that receives pointers to the pages pinned.
- * Should be at least nr_pages long. Or NULL, if caller
- * only intends to ensure the pages are faulted in.
- * @locked: pointer to lock flag indicating whether lock is held and
- * subsequently whether VM_FAULT_RETRY functionality can be
- * utilised. Lock must initially be held.
- *
* We can leverage the VM_FAULT_RETRY functionality in the page fault
* paths better by using either get_user_pages_locked() or
* get_user_pages_unlocked().
*
*/
long get_user_pages_locked(unsigned long start, unsigned long nr_pages,
unsigned int gup_flags, struct page **pages,
int *locked)
{
/*
* FIXME: Current FOLL_LONGTERM behavior is incompatible with
* FAULT_FLAG_ALLOW_RETRY because of the FS DAX check requirement on
* vmas. As there are no users of this flag in this call we simply
* disallow this option for now.
*/
if (WARN_ON_ONCE(gup_flags & FOLL_LONGTERM))
return -EINVAL;
/*
* FOLL_PIN must only be set internally by the pin_user_pages*() APIs,
* never directly by the caller, so enforce that:
diff --git a/mm/page_alloc.c b/mm/page_alloc.c
index 63d8d8b72c10..7e4d1e4bdee9 100644
--- a/mm/page_alloc.c
+++ b/mm/page_alloc.c
@@ -478,66 +478,66 @@ static inline bool defer_init(int nid, unsigned long pfn, unsigned long end_pfn)
static inline unsigned long *get_pageblock_bitmap(struct page *page,
unsigned long pfn)
{
#ifdef CONFIG_SPARSEMEM
return section_to_usemap(__pfn_to_section(pfn));
#else
return page_zone(page)->pageblock_flags;
#endif /* CONFIG_SPARSEMEM */
}
static inline int pfn_to_bitidx(struct page *page, unsigned long pfn)
{
#ifdef CONFIG_SPARSEMEM
pfn &= (PAGES_PER_SECTION-1);
#else
pfn = pfn - round_down(page_zone(page)->zone_start_pfn, pageblock_nr_pages);
#endif /* CONFIG_SPARSEMEM */
return (pfn >> pageblock_order) * NR_PAGEBLOCK_BITS;
}
-/**
- * get_pfnblock_flags_mask - Return the requested group of flags for the pageblock_nr_pages block of pages
- * @page: The page within the block of interest
- * @pfn: The target page frame number
- * @mask: mask of bits that the caller is interested in
- *
- * Return: pageblock_bits flags
- */
static __always_inline
unsigned long __get_pfnblock_flags_mask(struct page *page,
unsigned long pfn,
unsigned long mask)
{
unsigned long *bitmap;
unsigned long bitidx, word_bitidx;
unsigned long word;
bitmap = get_pageblock_bitmap(page, pfn);
bitidx = pfn_to_bitidx(page, pfn);
word_bitidx = bitidx / BITS_PER_LONG;
bitidx &= (BITS_PER_LONG-1);
word = bitmap[word_bitidx];
return (word >> bitidx) & mask;
}
+/**
+ * get_pfnblock_flags_mask - Return the requested group of flags for the pageblock_nr_pages block of pages
+ * @page: The page within the block of interest
+ * @pfn: The target page frame number
+ * @mask: mask of bits that the caller is interested in
+ *
+ * Return: pageblock_bits flags
+ */
unsigned long get_pfnblock_flags_mask(struct page *page, unsigned long pfn,
unsigned long mask)
{
return __get_pfnblock_flags_mask(page, pfn, mask);
}
static __always_inline int get_pfnblock_migratetype(struct page *page, unsigned long pfn)
{
return __get_pfnblock_flags_mask(page, pfn, MIGRATETYPE_MASK);
}
/**
* set_pfnblock_flags_mask - Set the requested group of flags for a pageblock_nr_pages block of pages
* @page: The page within the block of interest
* @flags: The flags to set
* @pfn: The target page frame number
* @mask: mask of bits that the caller is interested in
*/
void set_pfnblock_flags_mask(struct page *page, unsigned long flags,
unsigned long pfn,
diff --git a/mm/truncate.c b/mm/truncate.c
index 960edf5803ca..604eaabc6d06 100644
--- a/mm/truncate.c
+++ b/mm/truncate.c
@@ -620,43 +620,49 @@ static unsigned long __invalidate_mapping_pages(struct address_space *mapping,
* @start: the offset 'from' which to invalidate
* @end: the offset 'to' which to invalidate (inclusive)
*
* This function only removes the unlocked pages, if you want to
* remove all the pages of one inode, you must call truncate_inode_pages.
*
* invalidate_mapping_pages() will not block on IO activity. It will not
* invalidate pages which are dirty, locked, under writeback or mapped into
* pagetables.
*
* Return: the number of the pages that were invalidated
*/
unsigned long invalidate_mapping_pages(struct address_space *mapping,
pgoff_t start, pgoff_t end)
{
return __invalidate_mapping_pages(mapping, start, end, NULL);
}
EXPORT_SYMBOL(invalidate_mapping_pages);
/**
- * This helper is similar with the above one, except that it accounts for pages
- * that are likely on a pagevec and count them in @nr_pagevec, which will used by
+ * invalidate_mapping_pagevec - This helper is similar to
+ * invalidate_mapping_pages(), except that it accounts for pages that are
+ * likely on a pagevec and count them in @nr_pagevec, which will be used by
* the caller.
+ *
+ * @mapping: the address_space which holds the pages to invalidate
+ * @start: the offset 'from' which to invalidate
+ * @end: the offset 'to' which to invalidate (inclusive)
+ *
*/
void invalidate_mapping_pagevec(struct address_space *mapping,
pgoff_t start, pgoff_t end, unsigned long *nr_pagevec)
{
__invalidate_mapping_pages(mapping, start, end, nr_pagevec);
}
/*
* This is like invalidate_complete_page(), except it ignores the page's
* refcount. We do this because invalidate_inode_pages2() needs stronger
* invalidation guarantees, and cannot afford to leave pages behind because
* shrink_page_list() has a temp ref on them, or because they're transiently
* sitting in the lru_cache_add() pagevecs.
*/
static int
invalidate_complete_page2(struct address_space *mapping, struct page *page)
{
unsigned long flags;
if (page->mapping != mapping)
--
2.28.0
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH v4 00/27]Fix several bad kernel-doc markups
2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 21/27] memblock: fix " Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 25/27] mm: " Mauro Carvalho Chehab
@ 2020-11-17 22:19 ` Jakub Kicinski
2 siblings, 0 replies; 4+ messages in thread
From: Jakub Kicinski @ 2020-11-17 22:19 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, linux-kernel, Jonathan Corbet,
David S. Miller, Theodore Ts'o, Alexander Viro,
Alexandre Bounine, Andrew Lunn, Andrew Morton, Andy Lutomirski,
Anna Schumaker, Anton Vorontsov, Ben Segall, Colin Cross,
Daniel Bristot de Oliveira, Daniel Vetter, David Airlie,
Dietmar Eggemann, Evgeniy Polyakov, Heiner Kallweit, Ingo Molnar,
Jan Kara, Juri Lelli, Kees Cook, Maarten Lankhorst, Matt Porter,
Maxime Ripard, Mel Gorman, Mike Rapoport, Peter Zijlstra,
Richard Gong, Russell King, Sebastian Reichel, Shuah Khan,
Steven Rostedt, Sudip Mukherjee, Thomas Gleixner,
Thomas Zimmermann, Tony Luck, Trond Myklebust, Vincent Guittot,
Will Drewry, dri-devel, intel-gfx, linux-ext4, linux-fbdev,
linux-fsdevel, linux-kselftest, linux-mm, linux-nfs, linux-rdma,
linux-s390, netdev, target-devel
On Mon, 16 Nov 2020 11:17:56 +0100 Mauro Carvalho Chehab wrote:
> Kernel-doc has always be limited to a probably bad documented
> rule:
>
> The kernel-doc markups should appear *imediatelly before* the
> function or data structure that it documents.
Applied 1-3 to net-next, thanks!
^ permalink raw reply [flat|nested] 4+ messages in thread