[linux-block.git] / include / linux / dm-bufio.h

/* SPDX-License-Identifier: GPL-2.0-only */
/*
 * Copyright (C) 2009-2011 Red Hat, Inc.
 *
 * Author: Mikulas Patocka <mpatocka@redhat.com>
 *
 * This file is released under the GPL.
 */

#ifndef _LINUX_DM_BUFIO_H
#define _LINUX_DM_BUFIO_H

#include <linux/blkdev.h>
#include <linux/types.h>

/*----------------------------------------------------------------*/

struct dm_bufio_client;
struct dm_buffer;

/*
 * Flags for dm_bufio_client_create
 */
#define DM_BUFIO_CLIENT_NO_SLEEP 0x1

/*
 * Create a buffered IO cache on a given device
 */
struct dm_bufio_client *
dm_bufio_client_create(struct block_device *bdev, unsigned int block_size,
		       unsigned int reserved_buffers, unsigned int aux_size,
		       void (*alloc_callback)(struct dm_buffer *),
		       void (*write_callback)(struct dm_buffer *),
		       unsigned int flags);

/*
 * Release a buffered IO cache.
 */
void dm_bufio_client_destroy(struct dm_bufio_client *c);

void dm_bufio_client_reset(struct dm_bufio_client *c);

/*
 * Set the sector range.
 * When this function is called, there must be no I/O in progress on the bufio
 * client.
 */
void dm_bufio_set_sector_offset(struct dm_bufio_client *c, sector_t start);

/*
 * WARNING: to avoid deadlocks, these conditions are observed:
 *
 * - At most one thread can hold at most "reserved_buffers" simultaneously.
 * - Each other threads can hold at most one buffer.
 * - Threads which call only dm_bufio_get can hold unlimited number of
 *   buffers.
 */

/*
 * Read a given block from disk. Returns pointer to data.  Returns a
 * pointer to dm_buffer that can be used to release the buffer or to make
 * it dirty.
 */
void *dm_bufio_read(struct dm_bufio_client *c, sector_t block,
		    struct dm_buffer **bp);

void *dm_bufio_read_with_ioprio(struct dm_bufio_client *c, sector_t block,
				struct dm_buffer **bp, unsigned short ioprio);

/*
 * Like dm_bufio_read, but return buffer from cache, don't read
 * it. If the buffer is not in the cache, return NULL.
 */
void *dm_bufio_get(struct dm_bufio_client *c, sector_t block,
		   struct dm_buffer **bp);

/*
 * Like dm_bufio_read, but don't read anything from the disk.  It is
 * expected that the caller initializes the buffer and marks it dirty.
 */
void *dm_bufio_new(struct dm_bufio_client *c, sector_t block,
		   struct dm_buffer **bp);

/*
 * Prefetch the specified blocks to the cache.
 * The function starts to read the blocks and returns without waiting for
 * I/O to finish.
 */
void dm_bufio_prefetch(struct dm_bufio_client *c,
		       sector_t block, unsigned int n_blocks);

void dm_bufio_prefetch_with_ioprio(struct dm_bufio_client *c,
				sector_t block, unsigned int n_blocks,
				unsigned short ioprio);

/*
 * Release a reference obtained with dm_bufio_{read,get,new}. The data
 * pointer and dm_buffer pointer is no longer valid after this call.
 */
void dm_bufio_release(struct dm_buffer *b);

/*
 * Mark a buffer dirty. It should be called after the buffer is modified.
 *
 * In case of memory pressure, the buffer may be written after
 * dm_bufio_mark_buffer_dirty, but before dm_bufio_write_dirty_buffers.  So
 * dm_bufio_write_dirty_buffers guarantees that the buffer is on-disk but
 * the actual writing may occur earlier.
 */
void dm_bufio_mark_buffer_dirty(struct dm_buffer *b);

/*
 * Mark a part of the buffer dirty.
 *
 * The specified part of the buffer is scheduled to be written. dm-bufio may
 * write the specified part of the buffer or it may write a larger superset.
 */
void dm_bufio_mark_partial_buffer_dirty(struct dm_buffer *b,
					unsigned int start, unsigned int end);

/*
 * Initiate writing of dirty buffers, without waiting for completion.
 */
void dm_bufio_write_dirty_buffers_async(struct dm_bufio_client *c);

/*
 * Write all dirty buffers. Guarantees that all dirty buffers created prior
 * to this call are on disk when this call exits.
 */
int dm_bufio_write_dirty_buffers(struct dm_bufio_client *c);

/*
 * Send an empty write barrier to the device to flush hardware disk cache.
 */
int dm_bufio_issue_flush(struct dm_bufio_client *c);

/*
 * Send a discard request to the underlying device.
 */
int dm_bufio_issue_discard(struct dm_bufio_client *c, sector_t block, sector_t count);

/*
 * Free the given buffer.
 * This is just a hint, if the buffer is in use or dirty, this function
 * does nothing.
 */
void dm_bufio_forget(struct dm_bufio_client *c, sector_t block);

/*
 * Free the given range of buffers.
 * This is just a hint, if the buffer is in use or dirty, this function
 * does nothing.
 */
void dm_bufio_forget_buffers(struct dm_bufio_client *c, sector_t block, sector_t n_blocks);

/*
 * Set the minimum number of buffers before cleanup happens.
 */
void dm_bufio_set_minimum_buffers(struct dm_bufio_client *c, unsigned int n);

unsigned int dm_bufio_get_block_size(struct dm_bufio_client *c);
sector_t dm_bufio_get_device_size(struct dm_bufio_client *c);
struct dm_io_client *dm_bufio_get_dm_io_client(struct dm_bufio_client *c);
sector_t dm_bufio_get_block_number(struct dm_buffer *b);
void *dm_bufio_get_block_data(struct dm_buffer *b);
void *dm_bufio_get_aux_data(struct dm_buffer *b);
struct dm_bufio_client *dm_bufio_get_client(struct dm_buffer *b);

/*----------------------------------------------------------------*/

#endif
Commit	Line	Data
	1	/* SPDX-License-Identifier: GPL-2.0-only */
	2	/*
	3	* Copyright (C) 2009-2011 Red Hat, Inc.
	4	*
	5	* Author: Mikulas Patocka <mpatocka@redhat.com>
	6	*
	7	* This file is released under the GPL.
	8	*/
	9
	10	#ifndef _LINUX_DM_BUFIO_H
	11	#define _LINUX_DM_BUFIO_H
	12
	13	#include <linux/blkdev.h>
	14	#include <linux/types.h>
	15
	16	/----------------------------------------------------------------/
	17
	18	struct dm_bufio_client;
	19	struct dm_buffer;
	20
	21	/*
	22	* Flags for dm_bufio_client_create
	23	*/
	24	#define DM_BUFIO_CLIENT_NO_SLEEP 0x1
	25
	26	/*
	27	* Create a buffered IO cache on a given device
	28	*/
	29	struct dm_bufio_client *
	30	dm_bufio_client_create(struct block_device *bdev, unsigned int block_size,
	31	unsigned int reserved_buffers, unsigned int aux_size,
	32	void (alloc_callback)(struct dm_buffer ),
	33	void (write_callback)(struct dm_buffer ),
	34	unsigned int flags);
	35
	36	/*
	37	* Release a buffered IO cache.
	38	*/
	39	void dm_bufio_client_destroy(struct dm_bufio_client *c);
	40
	41	void dm_bufio_client_reset(struct dm_bufio_client *c);
	42
	43	/*
	44	* Set the sector range.
	45	* When this function is called, there must be no I/O in progress on the bufio
	46	* client.
	47	*/
	48	void dm_bufio_set_sector_offset(struct dm_bufio_client *c, sector_t start);
	49
	50	/*
	51	* WARNING: to avoid deadlocks, these conditions are observed:
	52	*
	53	* - At most one thread can hold at most "reserved_buffers" simultaneously.
	54	* - Each other threads can hold at most one buffer.
	55	* - Threads which call only dm_bufio_get can hold unlimited number of
	56	* buffers.
	57	*/
	58
	59	/*
	60	* Read a given block from disk. Returns pointer to data. Returns a
	61	* pointer to dm_buffer that can be used to release the buffer or to make
	62	* it dirty.
	63	*/
	64	void dm_bufio_read(struct dm_bufio_client c, sector_t block,
	65	struct dm_buffer **bp);
	66
	67	void dm_bufio_read_with_ioprio(struct dm_bufio_client c, sector_t block,
	68	struct dm_buffer **bp, unsigned short ioprio);
	69
	70	/*
	71	* Like dm_bufio_read, but return buffer from cache, don't read
	72	* it. If the buffer is not in the cache, return NULL.
	73	*/
	74	void dm_bufio_get(struct dm_bufio_client c, sector_t block,
	75	struct dm_buffer **bp);
	76
	77	/*
	78	* Like dm_bufio_read, but don't read anything from the disk. It is
	79	* expected that the caller initializes the buffer and marks it dirty.
	80	*/
	81	void dm_bufio_new(struct dm_bufio_client c, sector_t block,
	82	struct dm_buffer **bp);
	83
	84	/*
	85	* Prefetch the specified blocks to the cache.
	86	* The function starts to read the blocks and returns without waiting for
	87	* I/O to finish.
	88	*/
	89	void dm_bufio_prefetch(struct dm_bufio_client *c,
	90	sector_t block, unsigned int n_blocks);
	91
	92	void dm_bufio_prefetch_with_ioprio(struct dm_bufio_client *c,
	93	sector_t block, unsigned int n_blocks,
	94	unsigned short ioprio);
	95
	96	/*
	97	* Release a reference obtained with dm_bufio_{read,get,new}. The data
	98	* pointer and dm_buffer pointer is no longer valid after this call.
	99	*/
	100	void dm_bufio_release(struct dm_buffer *b);
	101
	102	/*
	103	* Mark a buffer dirty. It should be called after the buffer is modified.
	104	*
	105	* In case of memory pressure, the buffer may be written after
	106	* dm_bufio_mark_buffer_dirty, but before dm_bufio_write_dirty_buffers. So
	107	* dm_bufio_write_dirty_buffers guarantees that the buffer is on-disk but
	108	* the actual writing may occur earlier.
	109	*/
	110	void dm_bufio_mark_buffer_dirty(struct dm_buffer *b);
	111
	112	/*
	113	* Mark a part of the buffer dirty.
	114	*
	115	* The specified part of the buffer is scheduled to be written. dm-bufio may
	116	* write the specified part of the buffer or it may write a larger superset.
	117	*/
	118	void dm_bufio_mark_partial_buffer_dirty(struct dm_buffer *b,
	119	unsigned int start, unsigned int end);
	120
	121	/*
	122	* Initiate writing of dirty buffers, without waiting for completion.
	123	*/
	124	void dm_bufio_write_dirty_buffers_async(struct dm_bufio_client *c);
	125
	126	/*
	127	* Write all dirty buffers. Guarantees that all dirty buffers created prior
	128	* to this call are on disk when this call exits.
	129	*/
	130	int dm_bufio_write_dirty_buffers(struct dm_bufio_client *c);
	131
	132	/*
	133	* Send an empty write barrier to the device to flush hardware disk cache.
	134	*/
	135	int dm_bufio_issue_flush(struct dm_bufio_client *c);
	136
	137	/*
	138	* Send a discard request to the underlying device.
	139	*/
	140	int dm_bufio_issue_discard(struct dm_bufio_client *c, sector_t block, sector_t count);
	141
	142	/*
	143	* Free the given buffer.
	144	* This is just a hint, if the buffer is in use or dirty, this function
	145	* does nothing.
	146	*/
	147	void dm_bufio_forget(struct dm_bufio_client *c, sector_t block);
	148
	149	/*
	150	* Free the given range of buffers.
	151	* This is just a hint, if the buffer is in use or dirty, this function
	152	* does nothing.
	153	*/
	154	void dm_bufio_forget_buffers(struct dm_bufio_client *c, sector_t block, sector_t n_blocks);
	155
	156	/*
	157	* Set the minimum number of buffers before cleanup happens.
	158	*/
	159	void dm_bufio_set_minimum_buffers(struct dm_bufio_client *c, unsigned int n);
	160
	161	unsigned int dm_bufio_get_block_size(struct dm_bufio_client *c);
	162	sector_t dm_bufio_get_device_size(struct dm_bufio_client *c);
	163	struct dm_io_client dm_bufio_get_dm_io_client(struct dm_bufio_client c);
	164	sector_t dm_bufio_get_block_number(struct dm_buffer *b);
	165	void dm_bufio_get_block_data(struct dm_buffer b);
	166	void dm_bufio_get_aux_data(struct dm_buffer b);
	167	struct dm_bufio_client dm_bufio_get_client(struct dm_buffer b);
	168
	169	/----------------------------------------------------------------/
	170
	171	#endif