docs/core-api/mm: fix return value descriptions in mm/

 * @size: size of the blocks in this pool.

 * @align: alignment requirement for blocks; must be a power of two

 * @boundary: returned blocks won't cross this power of two boundary

 * Context: !in_interrupt()

 * Context: not in_interrupt()

 *

 * Returns a dma allocation pool with the requested characteristics, or

 * null if one can't be created.  Given one of these pools, dma_pool_alloc()

 * Given one of these pools, dma_pool_alloc()

 * may be used to allocate memory.  Such memory will all have "consistent"

 * DMA mappings, accessible by the device and its driver without using

 * cache flushing primitives.  The actual size of blocks allocated may be

 * cross that size boundary.  This is useful for devices which have

 * addressing restrictions on individual DMA transfers, such as not crossing

 * boundaries of 4KBytes.

 *

 * Return: a dma allocation pool with the requested characteristics, or

 * %NULL if one can't be created.

 */

struct dma_pool *dma_pool_create(const char *name, struct device *dev,

				 size_t size, size_t align, size_t boundary)

 * @mem_flags: GFP_* bitmask

 * @handle: pointer to dma address of block

 *

 * This returns the kernel virtual address of a currently unused block,

 * Return: the kernel virtual address of a currently unused block,

 * and reports its dma address through the handle.

 * If such a memory block can't be allocated, %NULL is returned.

 */

 *

 * Managed dma_pool_create().  DMA pool created with this function is

 * automatically destroyed on driver detach.

 *

 * Return: a managed dma allocation pool with the requested

 * characteristics, or %NULL if one can't be created.

 */

struct dma_pool *dmam_pool_create(const char *name, struct device *dev,

				  size_t size, size_t align, size_t allocation)

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

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

 * be waited upon, and not just skipped over.

 *

 * Return: %0 on success, negative error code otherwise.

 */

int __filemap_fdatawrite_range(struct address_space *mapping, loff_t start,

				loff_t end, int sync_mode)

 *

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

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

 *

 * Return: %0 on success, negative error code otherwise.

 */

int filemap_flush(struct address_space *mapping)

{

 *

 * Find at least one page in the range supplied, usually used to check if

 * direct writing in this range will trigger a writeback.

 *

 * Return: %true if at least one page exists in the specified range,

 * %false otherwise.

 */

bool filemap_range_has_page(struct address_space *mapping,

			   loff_t start_byte, loff_t end_byte)

 * Since the error status of the address space is cleared by this function,

 * callers are responsible for checking the return value and handling and/or

 * reporting the error.

 *

 * Return: error status of the address space.

 */

int filemap_fdatawait_range(struct address_space *mapping, loff_t start_byte,

			    loff_t end_byte)

 * Since the error status of the file is advanced by this function,

 * callers are responsible for checking the return value and handling and/or

 * reporting the error.

 *

 * Return: error status of the address space vs. the file->f_wb_err cursor.

 */

int file_fdatawait_range(struct file *file, loff_t start_byte, loff_t end_byte)

{

 * Use this function if callers don't handle errors themselves.  Expected

 * call sites are system-wide / filesystem-wide data flushers: e.g. sync(2),

 * fsfreeze(8)

 *

 * Return: error status of the address space.

 */

int filemap_fdatawait_keep_errors(struct address_space *mapping)

{

 *

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

 * that this function can be used to write to the very end-of-file (end = -1).

 *

 * Return: error status of the address space.

 */

int filemap_write_and_wait_range(struct address_space *mapping,

				 loff_t lstart, loff_t lend)

 * While we handle mapping->wb_err with atomic operations, the f_wb_err

 * value is protected by the f_lock since we must ensure that it reflects

 * the latest value swapped in for this file descriptor.

 *

 * Return: %0 on success, negative error code otherwise.

 */

int file_check_and_advance_wb_err(struct file *file)

{

 *

 * After writing out and waiting on the data, we check and advance the

 * f_wb_err cursor to the latest value, and return any errors detected there.

 *

 * Return: %0 on success, negative error code otherwise.

 */

int file_write_and_wait_range(struct file *file, loff_t lstart, loff_t lend)

{

 * caller must do that.

 *

 * The remove + add is atomic.  This function cannot fail.

 *

 * Return: %0

 */

int replace_page_cache_page(struct page *old, struct page *new, gfp_t gfp_mask)

{

 *

 * This function is used to add a page to the pagecache. It must be locked.

 * This function does not add the page to the LRU.  The caller must do that.

 *

 * Return: %0 on success, negative error code otherwise.

 */

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

		pgoff_t offset, gfp_t gfp_mask)

 * If the slot holds a shadow entry of a previously evicted page, or a

 * swap entry from shmem/tmpfs, it is returned.

 *

 * Otherwise, %NULL is returned.

 * Return: the found page or shadow entry, %NULL if nothing is found.

 */

struct page *find_get_entry(struct address_space *mapping, pgoff_t offset)

{

 * If the slot holds a shadow entry of a previously evicted page, or a

 * swap entry from shmem/tmpfs, it is returned.

 *

 * Otherwise, %NULL is returned.

 *

 * find_lock_entry() may sleep.

 *

 * Return: the found page or shadow entry, %NULL if nothing is found.

 */

struct page *find_lock_entry(struct address_space *mapping, pgoff_t offset)

{

 * - FGP_CREAT: If page is not present then a new page is allocated using

 *   @gfp_mask and added to the page cache and the VM's LRU

 *   list. The page is returned locked and with an increased

 *   refcount. Otherwise, NULL is returned.

 *   refcount.

 *

 * If FGP_LOCK or FGP_CREAT are specified then the function may sleep even

 * if the GFP flags specified for FGP_CREAT are atomic.

 *

 * If there is a page cache page, it is returned with an increased refcount.

 *

 * Return: the found page or %NULL otherwise.

 */

struct page *pagecache_get_page(struct address_space *mapping, pgoff_t offset,

	int fgp_flags, gfp_t gfp_mask)

 * Any shadow entries of evicted pages, or swap entries from

 * shmem/tmpfs, are included in the returned array.

 *

 * find_get_entries() returns the number of pages and shadow entries

 * which were found.

 * Return: the number of pages and shadow entries which were found.

 */

unsigned find_get_entries(struct address_space *mapping,

			  pgoff_t start, unsigned int nr_entries,

 * indexes.  There may be holes in the indices due to not-present pages.

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

 *

 * find_get_pages_range() returns the number of pages which were found. If this

 * number is smaller than @nr_pages, the end of specified range has been

 * Return: the number of pages which were found. If this number is

 * smaller than @nr_pages, the end of specified range has been

 * reached.

 */

unsigned find_get_pages_range(struct address_space *mapping, pgoff_t *start,

 * find_get_pages_contig() works exactly like find_get_pages(), except

 * that the returned number of pages are guaranteed to be contiguous.

 *

 * find_get_pages_contig() returns the number of pages which were found.

 * Return: the number of pages which were found.

 */

unsigned find_get_pages_contig(struct address_space *mapping, pgoff_t index,

			       unsigned int nr_pages, struct page **pages)

 *

 * 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.

 *

 * Return: the number of pages which were found.

 */

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

			pgoff_t end, xa_mark_t tag, unsigned int nr_pages,

 *

 * Like find_get_entries, except we only return entries which are tagged with

 * @tag.

 *

 * Return: the number of entries which were found.

 */

unsigned find_get_entries_tag(struct address_space *mapping, pgoff_t start,

			xa_mark_t tag, unsigned int nr_entries,

 *

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

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

 *

 * Return:

 * * total number of bytes copied, including those the were already @written

 * * negative error code if nothing was copied

 */

static ssize_t generic_file_buffered_read(struct kiocb *iocb,

		struct iov_iter *iter, ssize_t written)

 *

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

 * that can use the page cache directly.

 * Return:

 * * number of bytes copied, even for partial reads

 * * negative error code if nothing was read

 */

ssize_t

generic_file_read_iter(struct kiocb *iocb, struct iov_iter *iter)

 *

 * 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.

 *

 * Return: %0 on success, negative error code otherwise.

 */

static int page_cache_read(struct file *file, pgoff_t offset, gfp_t gfp_mask)

{

 * has not been released.

 *

 * We never return with VM_FAULT_RETRY and a bit from VM_FAULT_ERROR set.

 *

 * Return: bitwise-OR of %VM_FAULT_ codes.

 */

vm_fault_t filemap_fault(struct vm_fault *vmf)

{

 * not set, try to fill the page and wait for it to become unlocked.

 *

 * If the page does not get brought uptodate, return -EIO.

 *

 * Return: up to date page on success, ERR_PTR() on failure.

 */

struct page *read_cache_page(struct address_space *mapping,

				pgoff_t index,

 * any new page allocations done using the specified allocation flags.

 *

 * If the page does not get brought uptodate, return -EIO.

 *

 * Return: up to date page on success, ERR_PTR() on failure.

 */

struct page *read_cache_page_gfp(struct address_space *mapping,

				pgoff_t index,

 * This function does *not* take care of syncing data in case of O_SYNC write.

 * A caller has to handle it. This is mainly due to the fact that we want to

 * avoid syncing under i_mutex.

 *

 * Return:

 * * number of bytes written, even for truncated writes

 * * negative error code if no data has been written at all

 */

ssize_t __generic_file_write_iter(struct kiocb *iocb, struct iov_iter *from)

{

 * This is a wrapper around __generic_file_write_iter() to be used by most

 * filesystems. It takes care of syncing the file in case of O_SYNC file

 * and acquires i_mutex as needed.

 * Return:

 * * negative error code if no data has been written at all of

 *   vfs_fsync_range() failed for a synchronous write

 * * number of bytes written, even for truncated writes

 */

ssize_t generic_file_write_iter(struct kiocb *iocb, struct iov_iter *from)

{

 * @gfp_mask: memory allocation flags (and I/O mode)

 *

 * The address_space is to try to release any data against the page

 * (presumably at page->private).  If the release was successful, return '1'.

 * Otherwise return zero.

 * (presumably at page->private).

 *

 * This may also be called if PG_fscache is set on a page, indicating that the

 * page is known to the local caching routines.

 * The @gfp_mask argument specifies whether I/O may be performed to release

 * this page (__GFP_IO), and whether the call may block (__GFP_RECLAIM & __GFP_FS).

 *

 * Return: %1 if the release was successful, otherwise return zero.

 */

int try_to_release_page(struct page *page, gfp_t gfp_mask)

{

 * under mm->mmap_sem write-lock, so it can change vma->vm_flags.

 * Caller must set VM_MIXEDMAP on vma if it wants to call this

 * function from other places, for example from page-fault handler.

 *

 * Return: %0 on success, negative error code otherwise.

 */

int vm_insert_page(struct vm_area_struct *vma, unsigned long addr,

			struct page *page)

 * @prot: page protection flags for this mapping

 *

 * Note: this is only safe if the mm semaphore is held when called.

 *

 * Return: %0 on success, negative error code otherwise.

 */

int remap_pfn_range(struct vm_area_struct *vma, unsigned long addr,

		    unsigned long pfn, unsigned long size, pgprot_t prot)

 *

 * NOTE! Some drivers might want to tweak vma->vm_page_prot first to get

 * whatever write-combining details or similar.

 *

 * Return: %0 on success, negative error code otherwise.

 */

int vm_iomap_memory(struct vm_area_struct *vma, phys_addr_t start, unsigned long len)

{

 *

 * This function handles all that is needed to finish a write page fault in a

 * shared mapping due to PTE being read-only once the mapped page is prepared.

 * It handles locking of PTE and modifying it. The function returns

 * VM_FAULT_WRITE on success, 0 when PTE got changed before we acquired PTE

 * lock.

 * It handles locking of PTE and modifying it.

 *

 * The function expects the page to be locked or other protection against

 * concurrent faults / writeback (such as DAX radix tree locks).

 *

 * Return: %VM_FAULT_WRITE on success, %0 when PTE got changed before

 * we acquired PTE lock.

 */

vm_fault_t finish_mkwrite_fault(struct vm_fault *vmf)

{

 *

 * Target users are page handler itself and implementations of

 * vm_ops->map_pages.

 *

 * Return: %0 on success, %VM_FAULT_ code in case of error.

 */

vm_fault_t alloc_set_pte(struct vm_fault *vmf, struct mem_cgroup *memcg,

		struct page *page)

 * This function handles all that is needed to finish a page fault once the

 * page to fault in is prepared. It handles locking of PTEs, inserts PTE for

 * given page, adds reverse page mapping, handles memcg charges and LRU

 * addition. The function returns 0 on success, VM_FAULT_ code in case of

 * error.

 * addition.

 *

 * The function expects the page to be locked and on success it consumes a

 * reference of a page being mapped (for the PTE which maps it).

 *

 * Return: %0 on success, %VM_FAULT_ code in case of error.

 */

vm_fault_t finish_fault(struct vm_fault *vmf)

{

 *

 * Only IO mappings and raw PFN mappings are allowed.

 *

 * Returns zero and the pfn at @pfn on success, -ve otherwise.

 * Return: zero and the pfn at @pfn on success, -ve otherwise.

 */

int follow_pfn(struct vm_area_struct *vma, unsigned long address,

	unsigned long *pfn)

 * @gup_flags:	flags modifying lookup behaviour

 *

 * The caller must hold a reference on @mm.

 *

 * Return: number of bytes copied from source to destination.

 */

int access_remote_vm(struct mm_struct *mm, unsigned long addr,

		void *buf, int len, unsigned int gup_flags)

 *

 * Like mempool_create(), but initializes the pool in (i.e. embedded in another

 * structure).

 *

 * Return: %0 on success, negative error code otherwise.

 */

int mempool_init(mempool_t *pool, int min_nr, mempool_alloc_t *alloc_fn,

		 mempool_free_t *free_fn, void *pool_data)

 * functions. This function might sleep. Both the alloc_fn() and the free_fn()

 * functions might sleep - as long as the mempool_alloc() function is not called

 * from IRQ contexts.

 *

 * Return: pointer to the created memory pool object or %NULL on error.

 */

mempool_t *mempool_create(int min_nr, mempool_alloc_t *alloc_fn,

				mempool_free_t *free_fn, void *pool_data)

 * Note, the caller must guarantee that no mempool_destroy is called

 * while this function is running. mempool_alloc() & mempool_free()

 * might be called (eg. from IRQ contexts) while this function executes.

 *

 * Return: %0 on success, negative error code otherwise.

 */

int mempool_resize(mempool_t *pool, int new_min_nr)

{

 * *never* fails when called from process contexts. (it might

 * fail if called from an IRQ context.)

 * Note: using __GFP_ZERO is not supported.

 *

 * Return: pointer to the allocated element or %NULL on error.

 */

void *mempool_alloc(mempool_t *pool, gfp_t gfp_mask)

{

 * node_dirtyable_memory - number of dirtyable pages in a node

 * @pgdat: the node

 *

 * Returns the node's number of pages potentially available for dirty

 * Return: the node's number of pages potentially available for dirty

 * page cache.  This is the base value for the per-node dirty limits.

 */

static unsigned long node_dirtyable_memory(struct pglist_data *pgdat)

/**

 * global_dirtyable_memory - number of globally dirtyable pages

 *

 * Returns the global number of pages potentially available for dirty

 * Return: the global number of pages potentially available for dirty

 * page cache.  This is the base value for the global dirty limits.

 */

static unsigned long global_dirtyable_memory(void)

 * node_dirty_limit - maximum number of dirty pages allowed in a node

 * @pgdat: the node

 *

 * Returns the maximum number of dirty pages allowed in a node, based

 * Return: the maximum number of dirty pages allowed in a node, based

 * on the node's dirtyable memory.

 */

static unsigned long node_dirty_limit(struct pglist_data *pgdat)

 * node_dirty_ok - tells whether a node is within its dirty limits

 * @pgdat: the node to check

 *

 * Returns %true when the dirty pages in @pgdat are within the node's

 * Return: %true when the dirty pages in @pgdat are within the node's

 * dirty limit, %false if the limit is exceeded.

 */

bool node_dirty_ok(struct pglist_data *pgdat)

 * __wb_calc_thresh - @wb's share of dirty throttling threshold

 * @dtc: dirty_throttle_context of interest

 *

 * Returns @wb's dirty limit in pages. The term "dirty" in the context of

 * dirty balancing includes all PG_dirty, PG_writeback and NFS unstable pages.

 *

 * Note that balance_dirty_pages() will only seriously take it as a hard limit

 * when sleeping max_pause per page is not enough to keep the dirty pages under

 * control. For example, when the device is completely stalled due to some error

 *

 * The wb's share of dirty limit will be adapting to its throughput and

 * bounded by the bdi->min_ratio and/or bdi->max_ratio parameters, if set.

 *

 * Return: @wb's dirty limit in pages. The term "dirty" in the context of

 * dirty balancing includes all PG_dirty, PG_writeback and NFS unstable pages.

 */

static unsigned long __wb_calc_thresh(struct dirty_throttle_control *dtc)

{

 * @wb: bdi_writeback of interest

 *

 * Determines whether background writeback should keep writing @wb or it's

 * clean enough.  Returns %true if writeback should continue.

 * clean enough.

 *

 * Return: %true if writeback should continue.

 */

bool wb_over_bg_thresh(struct bdi_writeback *wb)

{

 * lock/page writeback access order inversion - we should only ever lock

 * multiple pages in ascending page->index order, and looping back to the start

 * of the file violates that rule and causes deadlocks.

 *

 * Return: %0 on success, negative error code otherwise

 */

int write_cache_pages(struct address_space *mapping,

		      struct writeback_control *wbc, writepage_t writepage,

 *

 * This is a library function, which implements the writepages()

 * address_space_operation.

 *

 * Return: %0 on success, negative error code otherwise

 */

int generic_writepages(struct address_space *mapping,

		       struct writeback_control *wbc)

 *

 * Note that the mapping's AS_EIO/AS_ENOSPC flags will be cleared when this

 * function returns.

 *

 * Return: %0 on success, negative error code otherwise

 */

int write_one_page(struct page *page)

{