[deliverable/linux.git] / include / linux / fscache-cache.h

/* General filesystem caching backing cache interface
 *
 * Copyright (C) 2004-2007 Red Hat, Inc. All Rights Reserved.
 * Written by David Howells (dhowells@redhat.com)
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version
 * 2 of the License, or (at your option) any later version.
 *
 * NOTE!!! See:
 *
 *	Documentation/filesystems/caching/backend-api.txt
 *
 * for a description of the cache backend interface declared here.
 */

#ifndef _LINUX_FSCACHE_CACHE_H
#define _LINUX_FSCACHE_CACHE_H

#include <linux/fscache.h>
#include <linux/sched.h>
#include <linux/workqueue.h>

#define NR_MAXCACHES BITS_PER_LONG

struct fscache_cache;
struct fscache_cache_ops;
struct fscache_object;
struct fscache_operation;

/*
 * cache tag definition
 */
struct fscache_cache_tag {
	struct list_head	link;
	struct fscache_cache	*cache;		/* cache referred to by this tag */
	unsigned long		flags;
#define FSCACHE_TAG_RESERVED	0		/* T if tag is reserved for a cache */
	atomic_t		usage;
	char			name[0];	/* tag name */
};

/*
 * cache definition
 */
struct fscache_cache {
	const struct fscache_cache_ops *ops;
	struct fscache_cache_tag *tag;		/* tag representing this cache */
	struct kobject		*kobj;		/* system representation of this cache */
	struct list_head	link;		/* link in list of caches */
	size_t			max_index_size;	/* maximum size of index data */
	char			identifier[36];	/* cache label */

	/* node management */
	struct work_struct	op_gc;		/* operation garbage collector */
	struct list_head	object_list;	/* list of data/index objects */
	struct list_head	op_gc_list;	/* list of ops to be deleted */
	spinlock_t		object_list_lock;
	spinlock_t		op_gc_list_lock;
	atomic_t		object_count;	/* no. of live objects in this cache */
	struct fscache_object	*fsdef;		/* object for the fsdef index */
	unsigned long		flags;
#define FSCACHE_IOERROR		0	/* cache stopped on I/O error */
#define FSCACHE_CACHE_WITHDRAWN	1	/* cache has been withdrawn */
};

extern wait_queue_head_t fscache_cache_cleared_wq;

/*
 * operation to be applied to a cache object
 * - retrieval initiation operations are done in the context of the process
 *   that issued them, and not in an async thread pool
 */
typedef void (*fscache_operation_release_t)(struct fscache_operation *op);
typedef void (*fscache_operation_processor_t)(struct fscache_operation *op);

struct fscache_operation {
	struct work_struct	work;		/* record for async ops */
	struct list_head	pend_link;	/* link in object->pending_ops */
	struct fscache_object	*object;	/* object to be operated upon */

	unsigned long		flags;
#define FSCACHE_OP_TYPE		0x000f	/* operation type */
#define FSCACHE_OP_ASYNC	0x0001	/* - async op, processor may sleep for disk */
#define FSCACHE_OP_MYTHREAD	0x0002	/* - processing is done be issuing thread, not pool */
#define FSCACHE_OP_WAITING	4	/* cleared when op is woken */
#define FSCACHE_OP_EXCLUSIVE	5	/* exclusive op, other ops must wait */
#define FSCACHE_OP_DEAD		6	/* op is now dead */
#define FSCACHE_OP_DEC_READ_CNT	7	/* decrement object->n_reads on destruction */
#define FSCACHE_OP_KEEP_FLAGS	0xc0	/* flags to keep when repurposing an op */

	atomic_t		usage;
	unsigned		debug_id;	/* debugging ID */

	/* operation processor callback
	 * - can be NULL if FSCACHE_OP_WAITING is going to be used to perform
	 *   the op in a non-pool thread */
	fscache_operation_processor_t processor;

	/* operation releaser */
	fscache_operation_release_t release;
};

extern atomic_t fscache_op_debug_id;
extern void fscache_op_work_func(struct work_struct *work);

extern void fscache_enqueue_operation(struct fscache_operation *);
extern void fscache_put_operation(struct fscache_operation *);

/**
 * fscache_operation_init - Do basic initialisation of an operation
 * @op: The operation to initialise
 * @release: The release function to assign
 *
 * Do basic initialisation of an operation.  The caller must still set flags,
 * object and processor if needed.
 */
static inline void fscache_operation_init(struct fscache_operation *op,
					fscache_operation_processor_t processor,
					fscache_operation_release_t release)
{
	INIT_WORK(&op->work, fscache_op_work_func);
	atomic_set(&op->usage, 1);
	op->debug_id = atomic_inc_return(&fscache_op_debug_id);
	op->processor = processor;
	op->release = release;
	INIT_LIST_HEAD(&op->pend_link);
}

/*
 * data read operation
 */
struct fscache_retrieval {
	struct fscache_operation op;
	struct address_space	*mapping;	/* netfs pages */
	fscache_rw_complete_t	end_io_func;	/* function to call on I/O completion */
	void			*context;	/* netfs read context (pinned) */
	struct list_head	to_do;		/* list of things to be done by the backend */
	unsigned long		start_time;	/* time at which retrieval started */
};

typedef int (*fscache_page_retrieval_func_t)(struct fscache_retrieval *op,
					     struct page *page,
					     gfp_t gfp);

typedef int (*fscache_pages_retrieval_func_t)(struct fscache_retrieval *op,
					      struct list_head *pages,
					      unsigned *nr_pages,
					      gfp_t gfp);

/**
 * fscache_get_retrieval - Get an extra reference on a retrieval operation
 * @op: The retrieval operation to get a reference on
 *
 * Get an extra reference on a retrieval operation.
 */
static inline
struct fscache_retrieval *fscache_get_retrieval(struct fscache_retrieval *op)
{
	atomic_inc(&op->op.usage);
	return op;
}

/**
 * fscache_enqueue_retrieval - Enqueue a retrieval operation for processing
 * @op: The retrieval operation affected
 *
 * Enqueue a retrieval operation for processing by the FS-Cache thread pool.
 */
static inline void fscache_enqueue_retrieval(struct fscache_retrieval *op)
{
	fscache_enqueue_operation(&op->op);
}

/**
 * fscache_put_retrieval - Drop a reference to a retrieval operation
 * @op: The retrieval operation affected
 *
 * Drop a reference to a retrieval operation.
 */
static inline void fscache_put_retrieval(struct fscache_retrieval *op)
{
	fscache_put_operation(&op->op);
}

/*
 * cached page storage work item
 * - used to do three things:
 *   - batch writes to the cache
 *   - do cache writes asynchronously
 *   - defer writes until cache object lookup completion
 */
struct fscache_storage {
	struct fscache_operation op;
	pgoff_t			store_limit;	/* don't write more than this */
};

/*
 * cache operations
 */
struct fscache_cache_ops {
	/* name of cache provider */
	const char *name;

	/* allocate an object record for a cookie */
	struct fscache_object *(*alloc_object)(struct fscache_cache *cache,
					       struct fscache_cookie *cookie);

	/* look up the object for a cookie
	 * - return -ETIMEDOUT to be requeued
	 */
	int (*lookup_object)(struct fscache_object *object);

	/* finished looking up */
	void (*lookup_complete)(struct fscache_object *object);

	/* increment the usage count on this object (may fail if unmounting) */
	struct fscache_object *(*grab_object)(struct fscache_object *object);

	/* pin an object in the cache */
	int (*pin_object)(struct fscache_object *object);

	/* unpin an object in the cache */
	void (*unpin_object)(struct fscache_object *object);

	/* store the updated auxiliary data on an object */
	void (*update_object)(struct fscache_object *object);

	/* discard the resources pinned by an object and effect retirement if
	 * necessary */
	void (*drop_object)(struct fscache_object *object);

	/* dispose of a reference to an object */
	void (*put_object)(struct fscache_object *object);

	/* sync a cache */
	void (*sync_cache)(struct fscache_cache *cache);

	/* notification that the attributes of a non-index object (such as
	 * i_size) have changed */
	int (*attr_changed)(struct fscache_object *object);

	/* reserve space for an object's data and associated metadata */
	int (*reserve_space)(struct fscache_object *object, loff_t i_size);

	/* request a backing block for a page be read or allocated in the
	 * cache */
	fscache_page_retrieval_func_t read_or_alloc_page;

	/* request backing blocks for a list of pages be read or allocated in
	 * the cache */
	fscache_pages_retrieval_func_t read_or_alloc_pages;

	/* request a backing block for a page be allocated in the cache so that
	 * it can be written directly */
	fscache_page_retrieval_func_t allocate_page;

	/* request backing blocks for pages be allocated in the cache so that
	 * they can be written directly */
	fscache_pages_retrieval_func_t allocate_pages;

	/* write a page to its backing block in the cache */
	int (*write_page)(struct fscache_storage *op, struct page *page);

	/* detach backing block from a page (optional)
	 * - must release the cookie lock before returning
	 * - may sleep
	 */
	void (*uncache_page)(struct fscache_object *object,
			     struct page *page);

	/* dissociate a cache from all the pages it was backing */
	void (*dissociate_pages)(struct fscache_cache *cache);
};

/*
 * data file or index object cookie
 * - a file will only appear in one cache
 * - a request to cache a file may or may not be honoured, subject to
 *   constraints such as disk space
 * - indices are created on disk just-in-time
 */
struct fscache_cookie {
	atomic_t			usage;		/* number of users of this cookie */
	atomic_t			n_children;	/* number of children of this cookie */
	spinlock_t			lock;
	spinlock_t			stores_lock;	/* lock on page store tree */
	struct hlist_head		backing_objects; /* object(s) backing this file/index */
	const struct fscache_cookie_def	*def;		/* definition */
	struct fscache_cookie		*parent;	/* parent of this entry */
	void				*netfs_data;	/* back pointer to netfs */
	struct radix_tree_root		stores;		/* pages to be stored on this cookie */
#define FSCACHE_COOKIE_PENDING_TAG	0		/* pages tag: pending write to cache */
#define FSCACHE_COOKIE_STORING_TAG	1		/* pages tag: writing to cache */

	unsigned long			flags;
#define FSCACHE_COOKIE_LOOKING_UP	0	/* T if non-index cookie being looked up still */
#define FSCACHE_COOKIE_CREATING		1	/* T if non-index object being created still */
#define FSCACHE_COOKIE_NO_DATA_YET	2	/* T if new object with no cached data yet */
#define FSCACHE_COOKIE_PENDING_FILL	3	/* T if pending initial fill on object */
#define FSCACHE_COOKIE_FILLING		4	/* T if filling object incrementally */
#define FSCACHE_COOKIE_UNAVAILABLE	5	/* T if cookie is unavailable (error, etc) */
};

extern struct fscache_cookie fscache_fsdef_index;

/*
 * on-disk cache file or index handle
 */
struct fscache_object {
	enum fscache_object_state {
		FSCACHE_OBJECT_INIT,		/* object in initial unbound state */
		FSCACHE_OBJECT_LOOKING_UP,	/* looking up object */
		FSCACHE_OBJECT_CREATING,	/* creating object */

		/* active states */
		FSCACHE_OBJECT_AVAILABLE,	/* cleaning up object after creation */
		FSCACHE_OBJECT_ACTIVE,		/* object is usable */
		FSCACHE_OBJECT_UPDATING,	/* object is updating */

		/* terminal states */
		FSCACHE_OBJECT_DYING,		/* object waiting for accessors to finish */
		FSCACHE_OBJECT_LC_DYING,	/* object cleaning up after lookup/create */
		FSCACHE_OBJECT_ABORT_INIT,	/* abort the init state */
		FSCACHE_OBJECT_RELEASING,	/* releasing object */
		FSCACHE_OBJECT_RECYCLING,	/* retiring object */
		FSCACHE_OBJECT_WITHDRAWING,	/* withdrawing object */
		FSCACHE_OBJECT_DEAD,		/* object is now dead */
		FSCACHE_OBJECT__NSTATES
	} state;

	int			debug_id;	/* debugging ID */
	int			n_children;	/* number of child objects */
	int			n_ops;		/* number of ops outstanding on object */
	int			n_obj_ops;	/* number of object ops outstanding on object */
	int			n_in_progress;	/* number of ops in progress */
	int			n_exclusive;	/* number of exclusive ops queued */
	atomic_t		n_reads;	/* number of read ops in progress */
	spinlock_t		lock;		/* state and operations lock */

	unsigned long		lookup_jif;	/* time at which lookup started */
	unsigned long		event_mask;	/* events this object is interested in */
	unsigned long		events;		/* events to be processed by this object
						 * (order is important - using fls) */
#define FSCACHE_OBJECT_EV_REQUEUE	0	/* T if object should be requeued */
#define FSCACHE_OBJECT_EV_UPDATE	1	/* T if object should be updated */
#define FSCACHE_OBJECT_EV_CLEARED	2	/* T if accessors all gone */
#define FSCACHE_OBJECT_EV_ERROR		3	/* T if fatal error occurred during processing */
#define FSCACHE_OBJECT_EV_RELEASE	4	/* T if netfs requested object release */
#define FSCACHE_OBJECT_EV_RETIRE	5	/* T if netfs requested object retirement */
#define FSCACHE_OBJECT_EV_WITHDRAW	6	/* T if cache requested object withdrawal */
#define FSCACHE_OBJECT_EVENTS_MASK	0x7f	/* mask of all events*/

	unsigned long		flags;
#define FSCACHE_OBJECT_LOCK		0	/* T if object is busy being processed */
#define FSCACHE_OBJECT_PENDING_WRITE	1	/* T if object has pending write */
#define FSCACHE_OBJECT_WAITING		2	/* T if object is waiting on its parent */

	struct list_head	cache_link;	/* link in cache->object_list */
	struct hlist_node	cookie_link;	/* link in cookie->backing_objects */
	struct fscache_cache	*cache;		/* cache that supplied this object */
	struct fscache_cookie	*cookie;	/* netfs's file/index object */
	struct fscache_object	*parent;	/* parent object */
	struct work_struct	work;		/* attention scheduling record */
	struct list_head	dependents;	/* FIFO of dependent objects */
	struct list_head	dep_link;	/* link in parent's dependents list */
	struct list_head	pending_ops;	/* unstarted operations on this object */
#ifdef CONFIG_FSCACHE_OBJECT_LIST
	struct rb_node		objlist_link;	/* link in global object list */
#endif
	pgoff_t			store_limit;	/* current storage limit */
	loff_t			store_limit_l;	/* current storage limit */
};

extern const char *fscache_object_states[];

#define fscache_object_is_active(obj)			      \
	(!test_bit(FSCACHE_IOERROR, &(obj)->cache->flags) &&  \
	 (obj)->state >= FSCACHE_OBJECT_AVAILABLE &&	      \
	 (obj)->state < FSCACHE_OBJECT_DYING)

#define fscache_object_is_dead(obj)				\
	(test_bit(FSCACHE_IOERROR, &(obj)->cache->flags) &&	\
	 (obj)->state >= FSCACHE_OBJECT_DYING)

extern void fscache_object_work_func(struct work_struct *work);

/**
 * fscache_object_init - Initialise a cache object description
 * @object: Object description
 *
 * Initialise a cache object description to its basic values.
 *
 * See Documentation/filesystems/caching/backend-api.txt for a complete
 * description.
 */
static inline
void fscache_object_init(struct fscache_object *object,
			 struct fscache_cookie *cookie,
			 struct fscache_cache *cache)
{
	atomic_inc(&cache->object_count);

	object->state = FSCACHE_OBJECT_INIT;
	spin_lock_init(&object->lock);
	INIT_LIST_HEAD(&object->cache_link);
	INIT_HLIST_NODE(&object->cookie_link);
	INIT_WORK(&object->work, fscache_object_work_func);
	INIT_LIST_HEAD(&object->dependents);
	INIT_LIST_HEAD(&object->dep_link);
	INIT_LIST_HEAD(&object->pending_ops);
	object->n_children = 0;
	object->n_ops = object->n_in_progress = object->n_exclusive = 0;
	object->events = object->event_mask = 0;
	object->flags = 0;
	object->store_limit = 0;
	object->store_limit_l = 0;
	object->cache = cache;
	object->cookie = cookie;
	object->parent = NULL;
}

extern void fscache_object_lookup_negative(struct fscache_object *object);
extern void fscache_obtained_object(struct fscache_object *object);

#ifdef CONFIG_FSCACHE_OBJECT_LIST
extern void fscache_object_destroy(struct fscache_object *object);
#else
#define fscache_object_destroy(object) do {} while(0)
#endif

/**
 * fscache_object_destroyed - Note destruction of an object in a cache
 * @cache: The cache from which the object came
 *
 * Note the destruction and deallocation of an object record in a cache.
 */
static inline void fscache_object_destroyed(struct fscache_cache *cache)
{
	if (atomic_dec_and_test(&cache->object_count))
		wake_up_all(&fscache_cache_cleared_wq);
}

/**
 * fscache_object_lookup_error - Note an object encountered an error
 * @object: The object on which the error was encountered
 *
 * Note that an object encountered a fatal error (usually an I/O error) and
 * that it should be withdrawn as soon as possible.
 */
static inline void fscache_object_lookup_error(struct fscache_object *object)
{
	set_bit(FSCACHE_OBJECT_EV_ERROR, &object->events);
}

/**
 * fscache_set_store_limit - Set the maximum size to be stored in an object
 * @object: The object to set the maximum on
 * @i_size: The limit to set in bytes
 *
 * Set the maximum size an object is permitted to reach, implying the highest
 * byte that may be written.  Intended to be called by the attr_changed() op.
 *
 * See Documentation/filesystems/caching/backend-api.txt for a complete
 * description.
 */
static inline
void fscache_set_store_limit(struct fscache_object *object, loff_t i_size)
{
	object->store_limit_l = i_size;
	object->store_limit = i_size >> PAGE_SHIFT;
	if (i_size & ~PAGE_MASK)
		object->store_limit++;
}

/**
 * fscache_end_io - End a retrieval operation on a page
 * @op: The FS-Cache operation covering the retrieval
 * @page: The page that was to be fetched
 * @error: The error code (0 if successful)
 *
 * Note the end of an operation to retrieve a page, as covered by a particular
 * operation record.
 */
static inline void fscache_end_io(struct fscache_retrieval *op,
				  struct page *page, int error)
{
	op->end_io_func(page, op->context, error);
}

/*
 * out-of-line cache backend functions
 */
extern __printf(3, 4)
void fscache_init_cache(struct fscache_cache *cache,
			const struct fscache_cache_ops *ops,
			const char *idfmt, ...);

extern int fscache_add_cache(struct fscache_cache *cache,
			     struct fscache_object *fsdef,
			     const char *tagname);
extern void fscache_withdraw_cache(struct fscache_cache *cache);

extern void fscache_io_error(struct fscache_cache *cache);

extern void fscache_mark_pages_cached(struct fscache_retrieval *op,
				      struct pagevec *pagevec);

extern bool fscache_object_sleep_till_congested(signed long *timeoutp);

extern enum fscache_checkaux fscache_check_aux(struct fscache_object *object,
					       const void *data,
					       uint16_t datalen);

#endif /* _LINUX_FSCACHE_CACHE_H */
Commit	Line	Data
0dfc41d1 DH	1	/* General filesystem caching backing cache interface
	2	*
	3	* Copyright (C) 2004-2007 Red Hat, Inc. All Rights Reserved.
	4	* Written by David Howells (dhowells@redhat.com)
	5	*
	6	* This program is free software; you can redistribute it and/or
	7	* modify it under the terms of the GNU General Public License
	8	* as published by the Free Software Foundation; either version
	9	* 2 of the License, or (at your option) any later version.
	10	*
	11	* NOTE!!! See:
	12	*
	13	* Documentation/filesystems/caching/backend-api.txt
	14	*
	15	* for a description of the cache backend interface declared here.
	16	*/
	17
	18	#ifndef _LINUX_FSCACHE_CACHE_H
	19	#define _LINUX_FSCACHE_CACHE_H
	20
	21	#include <linux/fscache.h>
	22	#include <linux/sched.h>
8b8edefa	23	#include <linux/workqueue.h>
0dfc41d1 DH	24
	25	#define NR_MAXCACHES BITS_PER_LONG
	26
	27	struct fscache_cache;
	28	struct fscache_cache_ops;
	29	struct fscache_object;
	30	struct fscache_operation;
	31
0dfc41d1 DH	32	/*
	33	* cache tag definition
	34	*/
	35	struct fscache_cache_tag {
	36	struct list_head link;
	37	struct fscache_cache cache; / cache referred to by this tag */
	38	unsigned long flags;
	39	#define FSCACHE_TAG_RESERVED 0 /* T if tag is reserved for a cache */
	40	atomic_t usage;
	41	char name[0]; /* tag name */
	42	};
	43
	44	/*
	45	* cache definition
	46	*/
	47	struct fscache_cache {
	48	const struct fscache_cache_ops *ops;
	49	struct fscache_cache_tag tag; / tag representing this cache */
	50	struct kobject kobj; / system representation of this cache */
	51	struct list_head link; /* link in list of caches */
	52	size_t max_index_size; /* maximum size of index data */
	53	char identifier[36]; /* cache label */
	54
	55	/* node management */
	56	struct work_struct op_gc; /* operation garbage collector */
	57	struct list_head object_list; /* list of data/index objects */
	58	struct list_head op_gc_list; /* list of ops to be deleted */
	59	spinlock_t object_list_lock;
	60	spinlock_t op_gc_list_lock;
	61	atomic_t object_count; /* no. of live objects in this cache */
	62	struct fscache_object fsdef; / object for the fsdef index */
	63	unsigned long flags;
	64	#define FSCACHE_IOERROR 0 /* cache stopped on I/O error */
	65	#define FSCACHE_CACHE_WITHDRAWN 1 /* cache has been withdrawn */
	66	};
	67
	68	extern wait_queue_head_t fscache_cache_cleared_wq;
	69
	70	/*
	71	* operation to be applied to a cache object
	72	* - retrieval initiation operations are done in the context of the process
	73	* that issued them, and not in an async thread pool
	74	*/
	75	typedef void (fscache_operation_release_t)(struct fscache_operation op);
	76	typedef void (fscache_operation_processor_t)(struct fscache_operation op);
	77
	78	struct fscache_operation {
8af7c124	79	struct work_struct work; /* record for async ops */
0dfc41d1 DH	80	struct list_head pend_link; /* link in object->pending_ops */
	81	struct fscache_object object; / object to be operated upon */
	82
	83	unsigned long flags;
	84	#define FSCACHE_OP_TYPE 0x000f /* operation type */
8af7c124 TH	85	#define FSCACHE_OP_ASYNC 0x0001 /* - async op, processor may sleep for disk */
8af7c124 TH	86	#define FSCACHE_OP_MYTHREAD 0x0002 /* - processing is done be issuing thread, not pool */
0dfc41d1 DH	87	#define FSCACHE_OP_WAITING 4 /* cleared when op is woken */
	88	#define FSCACHE_OP_EXCLUSIVE 5 /* exclusive op, other ops must wait */
	89	#define FSCACHE_OP_DEAD 6 /* op is now dead */
4fbf4291 DH	90	#define FSCACHE_OP_DEC_READ_CNT 7 /* decrement object->n_reads on destruction */
4fbf4291 DH	91	#define FSCACHE_OP_KEEP_FLAGS 0xc0 /* flags to keep when repurposing an op */
0dfc41d1 DH	92
	93	atomic_t usage;
	94	unsigned debug_id; /* debugging ID */
	95
	96	/* operation processor callback
	97	* - can be NULL if FSCACHE_OP_WAITING is going to be used to perform
	98	* the op in a non-pool thread */
	99	fscache_operation_processor_t processor;
	100
	101	/* operation releaser */
	102	fscache_operation_release_t release;
	103	};
	104
	105	extern atomic_t fscache_op_debug_id;
8af7c124	106	extern void fscache_op_work_func(struct work_struct *work);
0dfc41d1 DH	107
	108	extern void fscache_enqueue_operation(struct fscache_operation *);
	109	extern void fscache_put_operation(struct fscache_operation *);
	110
	111	/**
	112	* fscache_operation_init - Do basic initialisation of an operation
	113	* @op: The operation to initialise
	114	* @release: The release function to assign
	115	*
	116	* Do basic initialisation of an operation. The caller must still set flags,
8af7c124	117	* object and processor if needed.
0dfc41d1 DH	118	*/
0dfc41d1 DH	119	static inline void fscache_operation_init(struct fscache_operation *op,
8af7c124 TH	120	fscache_operation_processor_t processor,
8af7c124 TH	121	fscache_operation_release_t release)
0dfc41d1	122	{
8af7c124	123	INIT_WORK(&op->work, fscache_op_work_func);
0dfc41d1 DH	124	atomic_set(&op->usage, 1);
0dfc41d1 DH	125	op->debug_id = atomic_inc_return(&fscache_op_debug_id);
8af7c124	126	op->processor = processor;
0dfc41d1 DH	127	op->release = release;
	128	INIT_LIST_HEAD(&op->pend_link);
	129	}
	130
0dfc41d1 DH	131	/*
	132	* data read operation
	133	*/
	134	struct fscache_retrieval {
	135	struct fscache_operation op;
	136	struct address_space mapping; / netfs pages */
	137	fscache_rw_complete_t end_io_func; /* function to call on I/O completion */
	138	void context; / netfs read context (pinned) */
	139	struct list_head to_do; /* list of things to be done by the backend */
	140	unsigned long start_time; /* time at which retrieval started */
	141	};
	142
	143	typedef int (fscache_page_retrieval_func_t)(struct fscache_retrieval op,
	144	struct page *page,
	145	gfp_t gfp);
	146
	147	typedef int (fscache_pages_retrieval_func_t)(struct fscache_retrieval op,
	148	struct list_head *pages,
	149	unsigned *nr_pages,
	150	gfp_t gfp);
	151
	152	/**
	153	* fscache_get_retrieval - Get an extra reference on a retrieval operation
	154	* @op: The retrieval operation to get a reference on
	155	*
	156	* Get an extra reference on a retrieval operation.
	157	*/
	158	static inline
	159	struct fscache_retrieval fscache_get_retrieval(struct fscache_retrieval op)
	160	{
	161	atomic_inc(&op->op.usage);
	162	return op;
	163	}
	164
	165	/**
	166	* fscache_enqueue_retrieval - Enqueue a retrieval operation for processing
	167	* @op: The retrieval operation affected
	168	*
	169	* Enqueue a retrieval operation for processing by the FS-Cache thread pool.
	170	*/
	171	static inline void fscache_enqueue_retrieval(struct fscache_retrieval *op)
	172	{
	173	fscache_enqueue_operation(&op->op);
	174	}
	175
	176	/**
	177	* fscache_put_retrieval - Drop a reference to a retrieval operation
	178	* @op: The retrieval operation affected
	179	*
	180	* Drop a reference to a retrieval operation.
	181	*/
	182	static inline void fscache_put_retrieval(struct fscache_retrieval *op)
	183	{
	184	fscache_put_operation(&op->op);
	185	}
	186
	187	/*
	188	* cached page storage work item
	189	* - used to do three things:
	190	* - batch writes to the cache
	191	* - do cache writes asynchronously
	192	* - defer writes until cache object lookup completion
	193	*/
	194	struct fscache_storage {
195	struct fscache_operation op;
196	pgoff_t store_limit; /* don't write more than this */
197	};
198
199	/*
200	* cache operations
201	*/
202	struct fscache_cache_ops {
203	/* name of cache provider */
204	const char *name;
205
206	/* allocate an object record for a cookie */
207	struct fscache_object (alloc_object)(struct fscache_cache *cache,
208	struct fscache_cookie *cookie);
209
fee096de DH	210	/* look up the object for a cookie
	211	* - return -ETIMEDOUT to be requeued
	212	*/
	213	int (lookup_object)(struct fscache_object object);
0dfc41d1 DH	214
	215	/* finished looking up */
	216	void (lookup_complete)(struct fscache_object object);
	217
	218	/* increment the usage count on this object (may fail if unmounting) */
	219	struct fscache_object (grab_object)(struct fscache_object *object);
	220
	221	/* pin an object in the cache */
	222	int (pin_object)(struct fscache_object object);
	223
	224	/* unpin an object in the cache */
	225	void (unpin_object)(struct fscache_object object);
	226
25985edc	227	/* store the updated auxiliary data on an object */
0dfc41d1 DH	228	void (update_object)(struct fscache_object object);
	229
	230	/* discard the resources pinned by an object and effect retirement if
	231	* necessary */
	232	void (drop_object)(struct fscache_object object);
	233
	234	/* dispose of a reference to an object */
	235	void (put_object)(struct fscache_object object);
	236
	237	/* sync a cache */
	238	void (sync_cache)(struct fscache_cache cache);
	239
	240	/* notification that the attributes of a non-index object (such as
	241	* i_size) have changed */
	242	int (attr_changed)(struct fscache_object object);
	243
	244	/* reserve space for an object's data and associated metadata */
	245	int (reserve_space)(struct fscache_object object, loff_t i_size);
	246
	247	/* request a backing block for a page be read or allocated in the
	248	* cache */
	249	fscache_page_retrieval_func_t read_or_alloc_page;
	250
	251	/* request backing blocks for a list of pages be read or allocated in
	252	* the cache */
	253	fscache_pages_retrieval_func_t read_or_alloc_pages;
	254
	255	/* request a backing block for a page be allocated in the cache so that
	256	* it can be written directly */
	257	fscache_page_retrieval_func_t allocate_page;
	258
	259	/* request backing blocks for pages be allocated in the cache so that
	260	* they can be written directly */
	261	fscache_pages_retrieval_func_t allocate_pages;
	262
	263	/* write a page to its backing block in the cache */
	264	int (write_page)(struct fscache_storage op, struct page *page);
	265
	266	/* detach backing block from a page (optional)
	267	* - must release the cookie lock before returning
	268	* - may sleep
	269	*/
	270	void (uncache_page)(struct fscache_object object,
	271	struct page *page);
	272
	273	/* dissociate a cache from all the pages it was backing */
	274	void (dissociate_pages)(struct fscache_cache cache);
	275	};
	276
	277	/*
	278	* data file or index object cookie
	279	* - a file will only appear in one cache
	280	* - a request to cache a file may or may not be honoured, subject to
	281	* constraints such as disk space
	282	* - indices are created on disk just-in-time
	283	*/
	284	struct fscache_cookie {
	285	atomic_t usage; /* number of users of this cookie */
	286	atomic_t n_children; /* number of children of this cookie */
	287	spinlock_t lock;
1bccf513	288	spinlock_t stores_lock; /* lock on page store tree */
0dfc41d1 DH	289	struct hlist_head backing_objects; /* object(s) backing this file/index */
	290	const struct fscache_cookie_def def; / definition */
	291	struct fscache_cookie parent; / parent of this entry */
	292	void netfs_data; / back pointer to netfs */
	293	struct radix_tree_root stores; /* pages to be stored on this cookie */
	294	#define FSCACHE_COOKIE_PENDING_TAG 0 /* pages tag: pending write to cache */
201a1542	295	#define FSCACHE_COOKIE_STORING_TAG 1 /* pages tag: writing to cache */
0dfc41d1 DH	296
	297	unsigned long flags;
	298	#define FSCACHE_COOKIE_LOOKING_UP 0 /* T if non-index cookie being looked up still */
	299	#define FSCACHE_COOKIE_CREATING 1 /* T if non-index object being created still */
	300	#define FSCACHE_COOKIE_NO_DATA_YET 2 /* T if new object with no cached data yet */
	301	#define FSCACHE_COOKIE_PENDING_FILL 3 /* T if pending initial fill on object */
	302	#define FSCACHE_COOKIE_FILLING 4 /* T if filling object incrementally */
	303	#define FSCACHE_COOKIE_UNAVAILABLE 5 /* T if cookie is unavailable (error, etc) */
	304	};
	305
	306	extern struct fscache_cookie fscache_fsdef_index;
	307
	308	/*
	309	* on-disk cache file or index handle
	310	*/
	311	struct fscache_object {
	312	enum fscache_object_state {
	313	FSCACHE_OBJECT_INIT, /* object in initial unbound state */
	314	FSCACHE_OBJECT_LOOKING_UP, /* looking up object */
	315	FSCACHE_OBJECT_CREATING, /* creating object */
	316
	317	/* active states */
	318	FSCACHE_OBJECT_AVAILABLE, /* cleaning up object after creation */
	319	FSCACHE_OBJECT_ACTIVE, /* object is usable */
	320	FSCACHE_OBJECT_UPDATING, /* object is updating */
	321
	322	/* terminal states */
	323	FSCACHE_OBJECT_DYING, /* object waiting for accessors to finish */
	324	FSCACHE_OBJECT_LC_DYING, /* object cleaning up after lookup/create */
	325	FSCACHE_OBJECT_ABORT_INIT, /* abort the init state */
	326	FSCACHE_OBJECT_RELEASING, /* releasing object */
	327	FSCACHE_OBJECT_RECYCLING, /* retiring object */
	328	FSCACHE_OBJECT_WITHDRAWING, /* withdrawing object */
	329	FSCACHE_OBJECT_DEAD, /* object is now dead */
440f0aff	330	FSCACHE_OBJECT__NSTATES
0dfc41d1 DH	331	} state;
	332
	333	int debug_id; /* debugging ID */
	334	int n_children; /* number of child objects */
	335	int n_ops; /* number of ops outstanding on object */
	336	int n_obj_ops; /* number of object ops outstanding on object */
	337	int n_in_progress; /* number of ops in progress */
	338	int n_exclusive; /* number of exclusive ops queued */
4fbf4291	339	atomic_t n_reads; /* number of read ops in progress */
0dfc41d1 DH	340	spinlock_t lock; /* state and operations lock */
	341
	342	unsigned long lookup_jif; /* time at which lookup started */
	343	unsigned long event_mask; /* events this object is interested in */
	344	unsigned long events; /* events to be processed by this object
	345	* (order is important - using fls) */
	346	#define FSCACHE_OBJECT_EV_REQUEUE 0 /* T if object should be requeued */
	347	#define FSCACHE_OBJECT_EV_UPDATE 1 /* T if object should be updated */
	348	#define FSCACHE_OBJECT_EV_CLEARED 2 /* T if accessors all gone */
	349	#define FSCACHE_OBJECT_EV_ERROR 3 /* T if fatal error occurred during processing */
	350	#define FSCACHE_OBJECT_EV_RELEASE 4 /* T if netfs requested object release */
	351	#define FSCACHE_OBJECT_EV_RETIRE 5 /* T if netfs requested object retirement */
	352	#define FSCACHE_OBJECT_EV_WITHDRAW 6 /* T if cache requested object withdrawal */
4fbf4291	353	#define FSCACHE_OBJECT_EVENTS_MASK 0x7f /* mask of all events*/
0dfc41d1 DH	354
	355	unsigned long flags;
	356	#define FSCACHE_OBJECT_LOCK 0 /* T if object is busy being processed */
	357	#define FSCACHE_OBJECT_PENDING_WRITE 1 /* T if object has pending write */
	358	#define FSCACHE_OBJECT_WAITING 2 /* T if object is waiting on its parent */
	359
	360	struct list_head cache_link; /* link in cache->object_list */
	361	struct hlist_node cookie_link; /* link in cookie->backing_objects */
	362	struct fscache_cache cache; / cache that supplied this object */
	363	struct fscache_cookie cookie; / netfs's file/index object */
	364	struct fscache_object parent; / parent object */
8b8edefa	365	struct work_struct work; /* attention scheduling record */
0dfc41d1 DH	366	struct list_head dependents; /* FIFO of dependent objects */
	367	struct list_head dep_link; /* link in parent's dependents list */
	368	struct list_head pending_ops; /* unstarted operations on this object */
4fbf4291 DH	369	#ifdef CONFIG_FSCACHE_OBJECT_LIST
	370	struct rb_node objlist_link; /* link in global object list */
	371	#endif
0dfc41d1	372	pgoff_t store_limit; /* current storage limit */
a17754fb	373	loff_t store_limit_l; /* current storage limit */
0dfc41d1 DH	374	};
	375
	376	extern const char *fscache_object_states[];
	377
	378	#define fscache_object_is_active(obj) \
	379	(!test_bit(FSCACHE_IOERROR, &(obj)->cache->flags) && \
	380	(obj)->state >= FSCACHE_OBJECT_AVAILABLE && \
	381	(obj)->state < FSCACHE_OBJECT_DYING)
	382
60d543ca DH	383	#define fscache_object_is_dead(obj) \
	384	(test_bit(FSCACHE_IOERROR, &(obj)->cache->flags) && \
	385	(obj)->state >= FSCACHE_OBJECT_DYING)
	386
8b8edefa	387	extern void fscache_object_work_func(struct work_struct *work);
0dfc41d1 DH	388
	389	/**
	390	* fscache_object_init - Initialise a cache object description
	391	* @object: Object description
	392	*
	393	* Initialise a cache object description to its basic values.
	394	*
	395	* See Documentation/filesystems/caching/backend-api.txt for a complete
	396	* description.
	397	*/
	398	static inline
	399	void fscache_object_init(struct fscache_object *object,
	400	struct fscache_cookie *cookie,
	401	struct fscache_cache *cache)
	402	{
	403	atomic_inc(&cache->object_count);
	404
	405	object->state = FSCACHE_OBJECT_INIT;
	406	spin_lock_init(&object->lock);
	407	INIT_LIST_HEAD(&object->cache_link);
	408	INIT_HLIST_NODE(&object->cookie_link);
8b8edefa	409	INIT_WORK(&object->work, fscache_object_work_func);
0dfc41d1 DH	410	INIT_LIST_HEAD(&object->dependents);
	411	INIT_LIST_HEAD(&object->dep_link);
	412	INIT_LIST_HEAD(&object->pending_ops);
	413	object->n_children = 0;
	414	object->n_ops = object->n_in_progress = object->n_exclusive = 0;
	415	object->events = object->event_mask = 0;
	416	object->flags = 0;
	417	object->store_limit = 0;
a17754fb	418	object->store_limit_l = 0;
0dfc41d1 DH	419	object->cache = cache;
	420	object->cookie = cookie;
	421	object->parent = NULL;
	422	}
	423
	424	extern void fscache_object_lookup_negative(struct fscache_object *object);
	425	extern void fscache_obtained_object(struct fscache_object *object);
	426
4fbf4291 DH	427	#ifdef CONFIG_FSCACHE_OBJECT_LIST
	428	extern void fscache_object_destroy(struct fscache_object *object);
	429	#else
	430	#define fscache_object_destroy(object) do {} while(0)
	431	#endif
	432
0dfc41d1 DH	433	/**
	434	* fscache_object_destroyed - Note destruction of an object in a cache
	435	* @cache: The cache from which the object came
	436	*
	437	* Note the destruction and deallocation of an object record in a cache.
	438	*/
	439	static inline void fscache_object_destroyed(struct fscache_cache *cache)
	440	{
	441	if (atomic_dec_and_test(&cache->object_count))
	442	wake_up_all(&fscache_cache_cleared_wq);
	443	}
	444
	445	/**
	446	* fscache_object_lookup_error - Note an object encountered an error
	447	* @object: The object on which the error was encountered
	448	*
	449	* Note that an object encountered a fatal error (usually an I/O error) and
	450	* that it should be withdrawn as soon as possible.
	451	*/
	452	static inline void fscache_object_lookup_error(struct fscache_object *object)
	453	{
	454	set_bit(FSCACHE_OBJECT_EV_ERROR, &object->events);
	455	}
	456
	457	/**
	458	* fscache_set_store_limit - Set the maximum size to be stored in an object
	459	* @object: The object to set the maximum on
	460	* @i_size: The limit to set in bytes
	461	*
	462	* Set the maximum size an object is permitted to reach, implying the highest
	463	* byte that may be written. Intended to be called by the attr_changed() op.
	464	*
	465	* See Documentation/filesystems/caching/backend-api.txt for a complete
	466	* description.
	467	*/
	468	static inline
	469	void fscache_set_store_limit(struct fscache_object *object, loff_t i_size)
	470	{
a17754fb	471	object->store_limit_l = i_size;
0dfc41d1 DH	472	object->store_limit = i_size >> PAGE_SHIFT;
	473	if (i_size & ~PAGE_MASK)
	474	object->store_limit++;
	475	}
	476
	477	/**
	478	* fscache_end_io - End a retrieval operation on a page
	479	* @op: The FS-Cache operation covering the retrieval
	480	* @page: The page that was to be fetched
	481	* @error: The error code (0 if successful)
	482	*
	483	* Note the end of an operation to retrieve a page, as covered by a particular
	484	* operation record.
	485	*/
	486	static inline void fscache_end_io(struct fscache_retrieval *op,
	487	struct page *page, int error)
	488	{
	489	op->end_io_func(page, op->context, error);
	490	}
	491
	492	/*
	493	* out-of-line cache backend functions
	494	*/
b9075fa9 JP	495	extern __printf(3, 4)
	496	void fscache_init_cache(struct fscache_cache *cache,
	497	const struct fscache_cache_ops *ops,
	498	const char *idfmt, ...);
0dfc41d1 DH	499
	500	extern int fscache_add_cache(struct fscache_cache *cache,
	501	struct fscache_object *fsdef,
	502	const char *tagname);
	503	extern void fscache_withdraw_cache(struct fscache_cache *cache);
	504
	505	extern void fscache_io_error(struct fscache_cache *cache);
	506
	507	extern void fscache_mark_pages_cached(struct fscache_retrieval *op,
	508	struct pagevec *pagevec);
	509
8b8edefa TH	510	extern bool fscache_object_sleep_till_congested(signed long *timeoutp);
8b8edefa TH	511
0dfc41d1 DH	512	extern enum fscache_checkaux fscache_check_aux(struct fscache_object *object,
	513	const void *data,
	514	uint16_t datalen);
	515
	516	#endif /* _LINUX_FSCACHE_CACHE_H */