[PATCH] kernel-doc for mm/filemap.c

}

}

/**

/**

 * filemap_fdatawrite_range - start writeback against all of a mapping's

 * __filemap_fdatawrite_range - start writeback on mapping dirty pages in range

 * dirty pages that lie within the byte offsets <start, end>

 * @mapping:	address space structure to write

 * @mapping:	address space structure to write

 * @start:	offset in bytes where the range starts

 * @start:	offset in bytes where the range starts

 * @end:	offset in bytes where the range ends (inclusive)

 * @end:	offset in bytes where the range ends (inclusive)

 * @sync_mode:	enable synchronous operation

 * @sync_mode:	enable synchronous operation

 *

 *

 * Start writeback against all of a mapping's dirty pages that lie

 * within the byte offsets <start, end> inclusive.

 *

 * If sync_mode is WB_SYNC_ALL then this is a "data integrity" operation, as

 * If sync_mode is WB_SYNC_ALL then this is a "data integrity" operation, as

 * opposed to a regular memory * cleansing writeback.  The difference between

 * opposed to a regular memory cleansing writeback.  The difference between

 * these two operations is that if a dirty page/buffer is encountered, it must

 * these two operations is that if a dirty page/buffer is encountered, it must

 * be waited upon, and not just skipped over.

 * be waited upon, and not just skipped over.

 */

 */

	return __filemap_fdatawrite_range(mapping, start, end, WB_SYNC_ALL);

	return __filemap_fdatawrite_range(mapping, start, end, WB_SYNC_ALL);

}

}

/*

/**

 * filemap_flush - mostly a non-blocking flush

 * @mapping:	target address_space

 *

 * This is a mostly non-blocking flush.  Not suitable for data-integrity

 * This is a mostly non-blocking flush.  Not suitable for data-integrity

 * purposes - I/O may not be started against all dirty pages.

 * purposes - I/O may not be started against all dirty pages.

 */

 */

}

}

EXPORT_SYMBOL(filemap_flush);

EXPORT_SYMBOL(filemap_flush);

/*

/**

 * wait_on_page_writeback_range - wait for writeback to complete

 * @mapping:	target address_space

 * @start:	beginning page index

 * @end:	ending page index

 *

 * Wait for writeback to complete against pages indexed by start->end

 * Wait for writeback to complete against pages indexed by start->end

 * inclusive

 * inclusive

 */

 */

	return ret;

	return ret;

}

}

/*

/**

 * sync_page_range - write and wait on all pages in the passed range

 * @inode:	target inode

 * @mapping:	target address_space

 * @pos:	beginning offset in pages to write

 * @count:	number of bytes to write

 *

 * Write and wait upon all the pages in the passed range.  This is a "data

 * Write and wait upon all the pages in the passed range.  This is a "data

 * integrity" operation.  It waits upon in-flight writeout before starting and

 * integrity" operation.  It waits upon in-flight writeout before starting and

 * waiting upon new writeout.  If there was an IO error, return it.

 * waiting upon new writeout.  If there was an IO error, return it.

}

}

EXPORT_SYMBOL(sync_page_range);

EXPORT_SYMBOL(sync_page_range);

/*

/**

 * sync_page_range_nolock

 * @inode:	target inode

 * @mapping:	target address_space

 * @pos:	beginning offset in pages to write

 * @count:	number of bytes to write

 *

 * Note: Holding i_mutex across sync_page_range_nolock is not a good idea

 * Note: Holding i_mutex across sync_page_range_nolock is not a good idea

 * as it forces O_SYNC writers to different parts of the same file

 * as it forces O_SYNC writers to different parts of the same file

 * to be serialised right until io completion.

 * to be serialised right until io completion.

EXPORT_SYMBOL(sync_page_range_nolock);

EXPORT_SYMBOL(sync_page_range_nolock);

/**

/**

 * filemap_fdatawait - walk the list of under-writeback pages of the given

 * filemap_fdatawait - wait for all under-writeback pages to complete

 *     address space and wait for all of them.

 *

 * @mapping: address space structure to wait for

 * @mapping: address space structure to wait for

 *

 * Walk the list of under-writeback pages of the given address space

 * and wait for all of them.

 */

 */

int filemap_fdatawait(struct address_space *mapping)

int filemap_fdatawait(struct address_space *mapping)

{

{

}

}

EXPORT_SYMBOL(filemap_write_and_wait);

EXPORT_SYMBOL(filemap_write_and_wait);

/*

/**

 * filemap_write_and_wait_range - write out & wait on a file range

 * @mapping:	the address_space for the pages

 * @lstart:	offset in bytes where the range starts

 * @lend:	offset in bytes where the range ends (inclusive)

 *

 * Write out and wait upon file offsets lstart->lend, inclusive.

 * Write out and wait upon file offsets lstart->lend, inclusive.

 *

 *

 * Note that `lend' is inclusive (describes the last byte to be written) so

 * Note that `lend' is inclusive (describes the last byte to be written) so

	return err;

	return err;

}

}

/*

/**

 * This function is used to add newly allocated pagecache pages:

 * add_to_page_cache - add newly allocated pagecache pages

 * @page:	page to add

 * @mapping:	the page's address_space

 * @offset:	page index

 * @gfp_mask:	page allocation mode

 *

 * This function is used to add newly allocated pagecache pages;

 * the page is new, so we can just run SetPageLocked() against it.

 * the page is new, so we can just run SetPageLocked() against it.

 * The other page state flags were set by rmqueue().

 * The other page state flags were set by rmqueue().

 *

 *

	}

	}

	return error;

	return error;

}

}

EXPORT_SYMBOL(add_to_page_cache);

EXPORT_SYMBOL(add_to_page_cache);

int add_to_page_cache_lru(struct page *page, struct address_space *mapping,

int add_to_page_cache_lru(struct page *page, struct address_space *mapping,

EXPORT_SYMBOL(wait_on_page_bit);

EXPORT_SYMBOL(wait_on_page_bit);

/**

/**

 * unlock_page() - unlock a locked page

 * unlock_page - unlock a locked page

 *

 * @page: the page

 * @page: the page

 *

 *

 * Unlocks the page and wakes up sleepers in ___wait_on_page_locked().

 * Unlocks the page and wakes up sleepers in ___wait_on_page_locked().

}

}

EXPORT_SYMBOL(unlock_page);

EXPORT_SYMBOL(unlock_page);

/*

/**

 * End writeback against a page.

 * end_page_writeback - end writeback against a page

 * @page: the page

 */

 */

void end_page_writeback(struct page *page)

void end_page_writeback(struct page *page)

{

{

}

}

EXPORT_SYMBOL(end_page_writeback);

EXPORT_SYMBOL(end_page_writeback);

/*

/**

 * Get a lock on the page, assuming we need to sleep to get it.

 * __lock_page - get a lock on the page, assuming we need to sleep to get it

 * @page: the page to lock

 *

 *

 * Ugly: running sync_page() in state TASK_UNINTERRUPTIBLE is scary.  If some

 * Ugly. Running sync_page() in state TASK_UNINTERRUPTIBLE is scary.  If some

 * random driver's requestfn sets TASK_RUNNING, we could busywait.  However

 * random driver's requestfn sets TASK_RUNNING, we could busywait.  However

 * chances are that on the second loop, the block layer's plug list is empty,

 * chances are that on the second loop, the block layer's plug list is empty,

 * so sync_page() will then return in state TASK_UNINTERRUPTIBLE.

 * so sync_page() will then return in state TASK_UNINTERRUPTIBLE.

}

}

EXPORT_SYMBOL(__lock_page);

EXPORT_SYMBOL(__lock_page);

/*

/**

 * a rather lightweight function, finding and getting a reference to a

 * find_get_page - find and get a page reference

 * @mapping: the address_space to search

 * @offset: the page index

 *

 * A rather lightweight function, finding and getting a reference to a

 * hashed page atomically.

 * hashed page atomically.

 */

 */

struct page * find_get_page(struct address_space *mapping, unsigned long offset)

struct page * find_get_page(struct address_space *mapping, unsigned long offset)

	read_unlock_irq(&mapping->tree_lock);

	read_unlock_irq(&mapping->tree_lock);

	return page;

	return page;

}

}

EXPORT_SYMBOL(find_get_page);

EXPORT_SYMBOL(find_get_page);

/*

/**

 * Same as above, but trylock it instead of incrementing the count.

 * find_trylock_page - find and lock a page

 * @mapping: the address_space to search

 * @offset: the page index

 *

 * Same as find_get_page(), but trylock it instead of incrementing the count.

 */

 */

struct page *find_trylock_page(struct address_space *mapping, unsigned long offset)

struct page *find_trylock_page(struct address_space *mapping, unsigned long offset)

{

{

	read_unlock_irq(&mapping->tree_lock);

	read_unlock_irq(&mapping->tree_lock);

	return page;

	return page;

}

}

EXPORT_SYMBOL(find_trylock_page);

EXPORT_SYMBOL(find_trylock_page);

/**

/**

 * find_lock_page - locate, pin and lock a pagecache page

 * find_lock_page - locate, pin and lock a pagecache page

 *

 * @mapping: the address_space to search

 * @mapping: the address_space to search

 * @offset: the page index

 * @offset: the page index

 *

 *

	read_unlock_irq(&mapping->tree_lock);

	read_unlock_irq(&mapping->tree_lock);

	return page;

	return page;

}

}

EXPORT_SYMBOL(find_lock_page);

EXPORT_SYMBOL(find_lock_page);

/**

/**

 * find_or_create_page - locate or add a pagecache page

 * find_or_create_page - locate or add a pagecache page

 *

 * @mapping: the page's address_space

 * @mapping: the page's address_space

 * @index: the page's index into the mapping

 * @index: the page's index into the mapping

 * @gfp_mask: page allocation mode

 * @gfp_mask: page allocation mode

		page_cache_release(cached_page);

		page_cache_release(cached_page);

	return page;

	return page;

}

}

EXPORT_SYMBOL(find_or_create_page);

EXPORT_SYMBOL(find_or_create_page);

/**

/**

	return i;

	return i;

}

}

/*

/**

 * find_get_pages_tag - find and return pages that match @tag

 * @mapping:	the address_space to search

 * @index:	the starting page index

 * @tag:	the tag index

 * @nr_pages:	the maximum number of pages

 * @pages:	where the resulting pages are placed

 *

 * Like find_get_pages, except we only return pages which are tagged with

 * Like find_get_pages, except we only return pages which are tagged with

 * `tag'.   We update *index to index the next page for the traversal.

 * @tag.   We update @index to index the next page for the traversal.

 */

 */

unsigned find_get_pages_tag(struct address_space *mapping, pgoff_t *index,

unsigned find_get_pages_tag(struct address_space *mapping, pgoff_t *index,

			int tag, unsigned int nr_pages, struct page **pages)

			int tag, unsigned int nr_pages, struct page **pages)

	return ret;

	return ret;

}

}

/*

/**

 * grab_cache_page_nowait - returns locked page at given index in given cache

 * @mapping: target address_space

 * @index: the page index

 *

 * Same as grab_cache_page, but do not wait if the page is unavailable.

 * Same as grab_cache_page, but do not wait if the page is unavailable.

 * This is intended for speculative data generators, where the data can

 * This is intended for speculative data generators, where the data can

 * be regenerated if the page couldn't be grabbed.  This routine should

 * be regenerated if the page couldn't be grabbed.  This routine should

	}

	}

	return page;

	return page;

}

}

EXPORT_SYMBOL(grab_cache_page_nowait);

EXPORT_SYMBOL(grab_cache_page_nowait);

/*

/**

 * do_generic_mapping_read - generic file read routine

 * @mapping:	address_space to be read

 * @_ra:	file's readahead state

 * @filp:	the file to read

 * @ppos:	current file position

 * @desc:	read_descriptor

 * @actor:	read method

 *

 * This is a generic file read routine, and uses the

 * This is a generic file read routine, and uses the

 * mapping->a_ops->readpage() function for the actual low-level

 * mapping->a_ops->readpage() function for the actual low-level stuff.

 * stuff.

 *

 *

 * This is really ugly. But the goto's actually try to clarify some

 * This is really ugly. But the goto's actually try to clarify some

 * of the logic when it comes to error handling etc.

 * of the logic when it comes to error handling etc.

 *

 *

 * Note the struct file* is only passed for the use of readpage.  It may be

 * Note the struct file* is only passed for the use of readpage.

 * NULL.

 * It may be NULL.

 */

 */

void do_generic_mapping_read(struct address_space *mapping,

void do_generic_mapping_read(struct address_space *mapping,

			     struct file_ra_state *_ra,

			     struct file_ra_state *_ra,

	if (filp)

	if (filp)

		file_accessed(filp);

		file_accessed(filp);

}

}

EXPORT_SYMBOL(do_generic_mapping_read);

EXPORT_SYMBOL(do_generic_mapping_read);

int file_read_actor(read_descriptor_t *desc, struct page *page,

int file_read_actor(read_descriptor_t *desc, struct page *page,

	return size;

	return size;

}

}

/*

/**

 * __generic_file_aio_read - generic filesystem read routine

 * @iocb:	kernel I/O control block

 * @iov:	io vector request

 * @nr_segs:	number of segments in the iovec

 * @ppos:	current file position

 *

 * This is the "read()" routine for all filesystems

 * This is the "read()" routine for all filesystems

 * that can use the page cache directly.

 * that can use the page cache directly.

 */

 */

out:

out:

	return retval;

	return retval;

}

}

EXPORT_SYMBOL(__generic_file_aio_read);

EXPORT_SYMBOL(__generic_file_aio_read);

ssize_t

ssize_t

	BUG_ON(iocb->ki_pos != pos);

	BUG_ON(iocb->ki_pos != pos);

	return __generic_file_aio_read(iocb, &local_iov, 1, &iocb->ki_pos);

	return __generic_file_aio_read(iocb, &local_iov, 1, &iocb->ki_pos);

}

}

EXPORT_SYMBOL(generic_file_aio_read);

EXPORT_SYMBOL(generic_file_aio_read);

ssize_t

ssize_t

		ret = wait_on_sync_kiocb(&kiocb);

		ret = wait_on_sync_kiocb(&kiocb);

	return ret;

	return ret;

}

}

EXPORT_SYMBOL(generic_file_read);

EXPORT_SYMBOL(generic_file_read);

int file_send_actor(read_descriptor_t * desc, struct page *page, unsigned long offset, unsigned long size)

int file_send_actor(read_descriptor_t * desc, struct page *page, unsigned long offset, unsigned long size)

		return desc.written;

		return desc.written;

	return desc.error;

	return desc.error;

}

}

EXPORT_SYMBOL(generic_file_sendfile);

EXPORT_SYMBOL(generic_file_sendfile);

static ssize_t

static ssize_t

}

}

#ifdef CONFIG_MMU

#ifdef CONFIG_MMU

/*

static int FASTCALL(page_cache_read(struct file * file, unsigned long offset));

/**

 * page_cache_read - adds requested page to the page cache if not already there

 * @file:	file to read

 * @offset:	page index

 *

 * This adds the requested page to the page cache if it isn't already there,

 * This adds the requested page to the page cache if it isn't already there,

 * and schedules an I/O to read in its contents from disk.

 * and schedules an I/O to read in its contents from disk.

 */

 */

static int FASTCALL(page_cache_read(struct file * file, unsigned long offset));

static int fastcall page_cache_read(struct file * file, unsigned long offset)

static int fastcall page_cache_read(struct file * file, unsigned long offset)

{

{

	struct address_space *mapping = file->f_mapping;

	struct address_space *mapping = file->f_mapping;

#define MMAP_LOTSAMISS  (100)

#define MMAP_LOTSAMISS  (100)

/*

/**

 * filemap_nopage - read in file data for page fault handling

 * @area:	the applicable vm_area

 * @address:	target address to read in

 * @type:	returned with VM_FAULT_{MINOR,MAJOR} if not %NULL

 *

 * filemap_nopage() is invoked via the vma operations vector for a

 * filemap_nopage() is invoked via the vma operations vector for a

 * mapped memory region to read in file data during a page fault.

 * mapped memory region to read in file data during a page fault.

 *

 *

	page_cache_release(page);

	page_cache_release(page);

	return NULL;

	return NULL;

}

}

EXPORT_SYMBOL(filemap_nopage);

EXPORT_SYMBOL(filemap_nopage);

static struct page * filemap_getpage(struct file *file, unsigned long pgoff,

static struct page * filemap_getpage(struct file *file, unsigned long pgoff,

	return page;

	return page;

}

}

/*

/**

 * read_cache_page - read into page cache, fill it if needed

 * @mapping:	the page's address_space

 * @index:	the page index

 * @filler:	function to perform the read

 * @data:	destination for read data

 *

 * Read into the page cache. If a page already exists,

 * Read into the page cache. If a page already exists,

 * and PageUptodate() is not set, try to fill the page.

 * and PageUptodate() is not set, try to fill the page.

 */

 */

 out:

 out:

	return page;

	return page;

}

}

EXPORT_SYMBOL(read_cache_page);

EXPORT_SYMBOL(read_cache_page);

/*

/*

/*

/*

 * Performs necessary checks before doing a write

 * Performs necessary checks before doing a write

 *

 *

 * Can adjust writing position aor amount of bytes to write.

 * Can adjust writing position or amount of bytes to write.

 * Returns appropriate error code that caller should return or

 * Returns appropriate error code that caller should return or

 * zero in case that write should be allowed.

 * zero in case that write should be allowed.

 */

 */