befs: improve documentation in datastream.c

Convert function descriptions to kernel-doc style.

Signed-off-by: Luis de Bethencourt <luisbg@osg.samsung.com>
Signed-off-by: Salah Triki <salah.triki@gmail.com>
This commit is contained in:
Luis de Bethencourt 2016-08-13 18:11:20 +01:00
parent d327e612bd
commit a20af5f9ea

View File

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