Messages in this thread | | | Date | Tue, 16 Aug 2016 08:34:36 +0100 | From | Salah Triki <> | Subject | Re: [PATCH 2/3] befs: improve documentation in datastream.c |
| |
On Sat, Aug 13, 2016 at 06:11:20PM +0100, Luis de Bethencourt wrote: > Convert function descriptions to kernel-doc style. > > Signed-off-by: Luis de Bethencourt <luisbg@osg.samsung.com> > --- > fs/befs/datastream.c | 193 ++++++++++++++++++++++++++------------------------- > 1 file changed, 98 insertions(+), 95 deletions(-) > > diff --git a/fs/befs/datastream.c b/fs/befs/datastream.c > index b2eb5b5..5ce85cf 100644 > --- a/fs/befs/datastream.c > +++ b/fs/befs/datastream.c > @@ -75,7 +75,13 @@ befs_read_datastream(struct super_block *sb, const befs_data_stream *ds, > return bh; > } > > -/* > +/** > + * befs_fblock2brun - give back block run for fblock > + * @sb: the superblock > + * @data: datastream to read from > + * @fblock: the blocknumber with the file position to find > + * @run: The found run is passed back through this pointer > + * > * Takes a file position and gives back a brun who's starting block > * is block number fblock of the file. > * > @@ -212,36 +218,35 @@ befs_count_blocks(struct super_block *sb, const befs_data_stream *ds) > return blocks; > } > > -/* > - Finds the block run that starts at file block number blockno > - in the file represented by the datastream data, if that > - blockno is in the direct region of the datastream. > - > - sb: the superblock > - data: the datastream > - blockno: the blocknumber to find > - run: The found run is passed back through this pointer > - > - Return value is BEFS_OK if the blockrun is found, BEFS_ERR > - otherwise. > - > - Algorithm: > - Linear search. Checks each element of array[] to see if it > - contains the blockno-th filesystem block. This is necessary > - because the block runs map variable amounts of data. Simply > - keeps a count of the number of blocks searched so far (sum), > - incrementing this by the length of each block run as we come > - across it. Adds sum to *count before returning (this is so > - you can search multiple arrays that are logicaly one array, > - as in the indirect region code). > - > - When/if blockno is found, if blockno is inside of a block > - run as stored on disk, we offset the start and length members > - of the block run, so that blockno is the start and len is > - still valid (the run ends in the same place). > - > - 2001-11-15 Will Dyson > -*/ > +/** > + * befs_find_brun_direct - find a direct block run in the datastream > + * @sb: the superblock > + * @data: the datastream > + * @blockno: the blocknumber to find > + * @run: The found run is passed back through this pointer > + * > + * Finds the block run that starts at file block number blockno > + * in the file represented by the datastream data, if that > + * blockno is in the direct region of the datastream. > + * > + * Return value is BEFS_OK if the blockrun is found, BEFS_ERR > + * otherwise. > + * > + * Algorithm: > + * Linear search. Checks each element of array[] to see if it > + * contains the blockno-th filesystem block. This is necessary > + * because the block runs map variable amounts of data. Simply > + * keeps a count of the number of blocks searched so far (sum), > + * incrementing this by the length of each block run as we come > + * across it. Adds sum to *count before returning (this is so > + * you can search multiple arrays that are logicaly one array, > + * as in the indirect region code). > + * > + * When/if blockno is found, if blockno is inside of a block > + * run as stored on disk, we offset the start and length members > + * of the block run, so that blockno is the start and len is > + * still valid (the run ends in the same place). > + */ > static int > befs_find_brun_direct(struct super_block *sb, const befs_data_stream *data, > befs_blocknr_t blockno, befs_block_run * run) > @@ -273,29 +278,28 @@ befs_find_brun_direct(struct super_block *sb, const befs_data_stream *data, > return BEFS_ERR; > } > > -/* > - Finds the block run that starts at file block number blockno > - in the file represented by the datastream data, if that > - blockno is in the indirect region of the datastream. > - > - sb: the superblock > - data: the datastream > - blockno: the blocknumber to find > - run: The found run is passed back through this pointer > - > - Return value is BEFS_OK if the blockrun is found, BEFS_ERR > - otherwise. > - > - Algorithm: > - For each block in the indirect run of the datastream, read > - it in and search through it for search_blk. > - > - XXX: > - Really should check to make sure blockno is inside indirect > - region. > - > - 2001-11-15 Will Dyson > -*/ > +/** > + * befs_find_brun_indirect - find a block run in the datastream > + * @sb: the superblock > + * @data: the datastream > + * @blockno: the blocknumber to find > + * @run: The found run is passed back through this pointer > + * > + * Finds the block run that starts at file block number blockno > + * in the file represented by the datastream data, if that > + * blockno is in the indirect region of the datastream. > + * > + * Return value is BEFS_OK if the blockrun is found, BEFS_ERR > + * otherwise. > + * > + * Algorithm: > + * For each block in the indirect run of the datastream, read > + * it in and search through it for search_blk. > + * > + * XXX: > + * Really should check to make sure blockno is inside indirect > + * region. > + */ > static int > befs_find_brun_indirect(struct super_block *sb, > const befs_data_stream *data, > @@ -365,47 +369,46 @@ befs_find_brun_indirect(struct super_block *sb, > return BEFS_ERR; > } > > -/* > - Finds the block run that starts at file block number blockno > - in the file represented by the datastream data, if that > - blockno is in the double-indirect region of the datastream. > - > - sb: the superblock > - data: the datastream > - blockno: the blocknumber to find > - run: The found run is passed back through this pointer > - > - Return value is BEFS_OK if the blockrun is found, BEFS_ERR > - otherwise. > - > - Algorithm: > - The block runs in the double-indirect region are different. > - They are always allocated 4 fs blocks at a time, so each > - block run maps a constant amount of file data. This means > - that we can directly calculate how many block runs into the > - double-indirect region we need to go to get to the one that > - maps a particular filesystem block. > - > - We do this in two stages. First we calculate which of the > - inode addresses in the double-indirect block will point us > - to the indirect block that contains the mapping for the data, > - then we calculate which of the inode addresses in that > - indirect block maps the data block we are after. > - > - Oh, and once we've done that, we actually read in the blocks > - that contain the inode addresses we calculated above. Even > - though the double-indirect run may be several blocks long, > - we can calculate which of those blocks will contain the index > - we are after and only read that one. We then follow it to > - the indirect block and perform a similar process to find > - the actual block run that maps the data block we are interested > - in. > - > - Then we offset the run as in befs_find_brun_array() and we are > - done. > - > - 2001-11-15 Will Dyson > -*/ > +/** > + * befs_find_brun_dblindirect - find a block run in the datastream > + * @sb: the superblock > + * @data: the datastream > + * @blockno: the blocknumber to find > + * @run: The found run is passed back through this pointer > + * > + * Finds the block run that starts at file block number blockno > + * in the file represented by the datastream data, if that > + * blockno is in the double-indirect region of the datastream. > + * > + * Return value is BEFS_OK if the blockrun is found, BEFS_ERR > + * otherwise. > + * > + * Algorithm: > + * The block runs in the double-indirect region are different. > + * They are always allocated 4 fs blocks at a time, so each > + * block run maps a constant amount of file data. This means > + * that we can directly calculate how many block runs into the > + * double-indirect region we need to go to get to the one that > + * maps a particular filesystem block. > + * > + * We do this in two stages. First we calculate which of the > + * inode addresses in the double-indirect block will point us > + * to the indirect block that contains the mapping for the data, > + * then we calculate which of the inode addresses in that > + * indirect block maps the data block we are after. > + * > + * Oh, and once we've done that, we actually read in the blocks > + * that contain the inode addresses we calculated above. Even > + * though the double-indirect run may be several blocks long, > + * we can calculate which of those blocks will contain the index > + * we are after and only read that one. We then follow it to > + * the indirect block and perform a similar process to find > + * the actual block run that maps the data block we are interested > + * in. > + * > + * Then we offset the run as in befs_find_brun_array() and we are > + * done. > + */ > static int > befs_find_brun_dblindirect(struct super_block *sb, > const befs_data_stream *data, > -- > 2.5.1 >
Signed-off-by: Salah Triki <salah.triki@gmail.com>
Thanks, Salah
| |