[<prev] [next>] [<thread-prev] [day] [month] [year] [list]
Message-ID: <20230821165755.flig4a2ooskrohbn@quack3>
Date: Mon, 21 Aug 2023 18:57:55 +0200
From: Jan Kara <jack@...e.cz>
To: "Matthew Wilcox (Oracle)" <willy@...radead.org>
Cc: Jan Kara <jack@...e.com>, linux-ext4@...r.kernel.org,
linux-docs@...r.kernel.org
Subject: Re: [PATCH] ext2: Fix kernel-doc warnings
On Fri 18-08-23 21:11:21, Matthew Wilcox (Oracle) wrote:
> Document a few parameters of ext2_alloc_blocks(). Redo the
> alloc_new_reservation() and find_next_reservable_window() kernel-doc
> entirely.
>
> Signed-off-by: Matthew Wilcox (Oracle) <willy@...radead.org>
Thanks, I've added the patch to my tree.
Honza
> ---
> fs/ext2/balloc.c | 101 +++++++++++++++++++++--------------------------
> fs/ext2/inode.c | 16 +++++---
> 2 files changed, 56 insertions(+), 61 deletions(-)
>
> diff --git a/fs/ext2/balloc.c b/fs/ext2/balloc.c
> index c8049c90323d..72c9f7f5918e 100644
> --- a/fs/ext2/balloc.c
> +++ b/fs/ext2/balloc.c
> @@ -716,36 +716,34 @@ ext2_try_to_allocate(struct super_block *sb, int group,
> }
>
> /**
> - * find_next_reservable_window():
> - * find a reservable space within the given range.
> - * It does not allocate the reservation window for now:
> - * alloc_new_reservation() will do the work later.
> + * find_next_reservable_window - Find a reservable space within the given range.
> + * @search_head: The list to search.
> + * @my_rsv: The reservation we're currently using.
> + * @sb: The super block.
> + * @start_block: The first block we consider to start the real search from
> + * @last_block: The maximum block number that our goal reservable space
> + * could start from.
> *
> - * @search_head: the head of the searching list;
> - * This is not necessarily the list head of the whole filesystem
> + * It does not allocate the reservation window: alloc_new_reservation()
> + * will do the work later.
> *
> - * We have both head and start_block to assist the search
> - * for the reservable space. The list starts from head,
> - * but we will shift to the place where start_block is,
> - * then start from there, when looking for a reservable space.
> + * We search the given range, rather than the whole reservation double
> + * linked list, (start_block, last_block) to find a free region that is
> + * of my size and has not been reserved.
> *
> - * @sb: the super block.
> + * @search_head is not necessarily the list head of the whole filesystem.
> + * We have both head and @start_block to assist the search for the
> + * reservable space. The list starts from head, but we will shift to
> + * the place where start_block is, then start from there, when looking
> + * for a reservable space.
> *
> - * @start_block: the first block we consider to start the real search from
> - *
> - * @last_block:
> - * the maximum block number that our goal reservable space
> - * could start from. This is normally the last block in this
> - * group. The search will end when we found the start of next
> - * possible reservable space is out of this boundary.
> - * This could handle the cross boundary reservation window
> - * request.
> - *
> - * basically we search from the given range, rather than the whole
> - * reservation double linked list, (start_block, last_block)
> - * to find a free region that is of my size and has not
> - * been reserved.
> + * @last_block is normally the last block in this group. The search will end
> + * when we found the start of next possible reservable space is out
> + * of this boundary. This could handle the cross boundary reservation
> + * window request.
> *
> + * Return: -1 if we could not find a range of sufficient size. If we could,
> + * return 0 and fill in @my_rsv with the range information.
> */
> static int find_next_reservable_window(
> struct ext2_reserve_window_node *search_head,
> @@ -833,41 +831,34 @@ static int find_next_reservable_window(
> }
>
> /**
> - * alloc_new_reservation()--allocate a new reservation window
> - *
> - * To make a new reservation, we search part of the filesystem
> - * reservation list (the list that inside the group). We try to
> - * allocate a new reservation window near the allocation goal,
> - * or the beginning of the group, if there is no goal.
> - *
> - * We first find a reservable space after the goal, then from
> - * there, we check the bitmap for the first free block after
> - * it. If there is no free block until the end of group, then the
> - * whole group is full, we failed. Otherwise, check if the free
> - * block is inside the expected reservable space, if so, we
> - * succeed.
> - * If the first free block is outside the reservable space, then
> - * start from the first free block, we search for next available
> - * space, and go on.
> - *
> - * on succeed, a new reservation will be found and inserted into the list
> - * It contains at least one free block, and it does not overlap with other
> - * reservation windows.
> + * alloc_new_reservation - Allocate a new reservation window.
> + * @my_rsv: The reservation we're currently using.
> + * @grp_goal: The goal block relative to the start of the group.
> + * @sb: The super block.
> + * @group: The group we are trying to allocate in.
> + * @bitmap_bh: The block group block bitmap.
> *
> - * failed: we failed to find a reservation window in this group
> + * To make a new reservation, we search part of the filesystem reservation
> + * list (the list inside the group). We try to allocate a new
> + * reservation window near @grp_goal, or the beginning of the
> + * group, if @grp_goal is negative.
> *
> - * @my_rsv: the reservation
> + * We first find a reservable space after the goal, then from there,
> + * we check the bitmap for the first free block after it. If there is
> + * no free block until the end of group, then the whole group is full,
> + * we failed. Otherwise, check if the free block is inside the expected
> + * reservable space, if so, we succeed.
> *
> - * @grp_goal: The goal (group-relative). It is where the search for a
> - * free reservable space should start from.
> - * if we have a goal(goal >0 ), then start from there,
> - * no goal(goal = -1), we start from the first block
> - * of the group.
> + * If the first free block is outside the reservable space, then start
> + * from the first free block, we search for next available space, and
> + * go on.
> *
> - * @sb: the super block
> - * @group: the group we are trying to allocate in
> - * @bitmap_bh: the block group block bitmap
> + * on succeed, a new reservation will be found and inserted into the
> + * list. It contains at least one free block, and it does not overlap
> + * with other reservation windows.
> *
> + * Return: 0 on success, -1 if we failed to find a reservation window
> + * in this group
> */
> static int alloc_new_reservation(struct ext2_reserve_window_node *my_rsv,
> ext2_grpblk_t grp_goal, struct super_block *sb,
> diff --git a/fs/ext2/inode.c b/fs/ext2/inode.c
> index acbab27fe957..693ba36ca9cd 100644
> --- a/fs/ext2/inode.c
> +++ b/fs/ext2/inode.c
> @@ -385,12 +385,16 @@ ext2_blks_to_allocate(Indirect * branch, int k, unsigned long blks,
> }
>
> /**
> - * ext2_alloc_blocks: multiple allocate blocks needed for a branch
> - * @indirect_blks: the number of blocks need to allocate for indirect
> - * blocks
> - * @blks: the number of blocks need to allocate for direct blocks
> - * @new_blocks: on return it will store the new block numbers for
> - * the indirect blocks(if needed) and the first direct block,
> + * ext2_alloc_blocks: Allocate multiple blocks needed for a branch.
> + * @inode: Owner.
> + * @goal: Preferred place for allocation.
> + * @indirect_blks: The number of blocks needed to allocate for indirect blocks.
> + * @blks: The number of blocks need to allocate for direct blocks.
> + * @new_blocks: On return it will store the new block numbers for
> + * the indirect blocks(if needed) and the first direct block.
> + * @err: Error pointer.
> + *
> + * Return: Number of blocks allocated.
> */
> static int ext2_alloc_blocks(struct inode *inode,
> ext2_fsblk_t goal, int indirect_blks, int blks,
> --
> 2.40.1
>
--
Jan Kara <jack@...e.com>
SUSE Labs, CR
Powered by blists - more mailing lists