--- /dev/null 2006-03-18 10:17:16.106812576 -0500 +++ linux-2.6.16.noarch/Documentation/filesystems/caching/backend-api.txt 2006-03-27 09:49:30.000000000 -0500 @@ -0,0 +1,334 @@ + ========================== + FS-CACHE CACHE BACKEND API + ========================== + +The FS-Cache system provides an API by which actual caches can be supplied to +FS-Cache for it to then serve out to network filesystems and other interested +parties. + +This API is declared in . + + +==================================== +INITIALISING AND REGISTERING A CACHE +==================================== + +To start off, a cache definition must be initialised and registered for each +cache the backend wants to make available. For instance, CacheFS does this in +the fill_super() operation on mounting. + +The cache definition (struct fscache_cache) should be initialised by calling: + + void fscache_init_cache(struct fscache_cache *cache, + struct fscache_cache_ops *ops, + const char *idfmt, + ...) + +Where: + + (*) "cache" is a pointer to the cache definition; + + (*) "ops" is a pointer to the table of operations that the backend supports on + this cache; + + (*) and a format and printf-style arguments for constructing a label for the + cache. + + +The cache should then be registered with FS-Cache by passing a pointer to the +previously initialised cache definition to: + + int fscache_add_cache(struct fscache_cache *cache, + struct fscache_object *fsdef, + const char *tagname); + +Two extra arguments should also be supplied: + + (*) "fsdef" which should point to the object representation for the FS-Cache + master index in this cache. Netfs primary index entries will be created + here. + + (*) "tagname" which, if given, should be a text string naming this cache. If + this is NULL, the identifier will be used instead. For CacheFS, the + identifier is set to name the underlying block device and the tag can be + supplied by mount. + +This function may return -ENOMEM if it ran out of memory or -EEXIST if the tag +is already in use. 0 will be returned on success. + + +===================== +UNREGISTERING A CACHE +===================== + +A cache can be withdrawn from the system by calling this function with a +pointer to the cache definition: + + void fscache_withdraw_cache(struct fscache_cache *cache) + +In CacheFS's case, this is called by put_super(). + + +================== +FS-CACHE UTILITIES +================== + +FS-Cache provides some utilities that a cache backend may make use of: + + (*) Find the parent of an object: + + struct fscache_object * + fscache_find_parent_object(struct fscache_object *object) + + This allows a backend to find the logical parent of an index or data file + in the cache hierarchy. + + +======================== +RELEVANT DATA STRUCTURES +======================== + + (*) Index/Data file FS-Cache representation cookie. + + struct fscache_cookie { + struct fscache_object_def *def; + struct fscache_netfs *netfs; + void *netfs_data; + ... + }; + + The fields that might be of use to the backend describe the object + definition, the netfs definition and the netfs's data for this + cookie. The object definition contain functions supplied by the netfs for + loading and matching index entries; these are required to provide some of + the cache operations. + + (*) In-cache object representation. + + struct fscache_object { + struct fscache_cache *cache; + struct fscache_cookie *cookie; + unsigned long flags; + #define FSCACHE_OBJECT_RECYCLING 1 + ... + }; + + Structures of this type should be allocated by the cache backend and + passed to FS-Cache when requested by the appropriate cache operation. In + the case of CacheFS, they're embedded in CacheFS's internal object + structures. + + Each object contains a pointer to the cookie that represents the object it + is backing. It also contains a flag that indicates whether this is an + index or not. This should be initialised by calling + fscache_object_init(object). + + +================ +CACHE OPERATIONS +================ + +The cache backend provides FS-Cache with a table of operations that can be +performed on the denizens of the cache. These are held in a structure of type + + struct fscache_cache_ops + + (*) Name of cache provider [mandatory]. + + const char *name + + This isn't strictly an operation, but should be pointed at a string naming + the backend. + + (*) Object lookup [mandatory]. + + struct fscache_object *(*lookup_object)(struct fscache_cache *cache, + struct fscache_object *parent, + struct fscache_cookie *cookie) + + This method is used to look up an object in the specified cache, given a + pointer to the parent object and the cookie to which the object will be + attached. This should instantiate that object in the cache if it can, or + return -ENOBUFS or -ENOMEM if it can't. + + (*) Increment object refcount [mandatory]. + + struct fscache_object *(*grab_object)(struct fscache_object *object) + + This method is called to increment the reference count on an object. It + may fail (for instance if the cache is being withdrawn) by returning + NULL. It should return the object pointer if successful. + + (*) Lock/Unlock object [mandatory]. + + void (*lock_object)(struct fscache_object *object) + void (*unlock_object)(struct fscache_object *object) + + These methods are used to exclusively lock an object. It must be possible + to schedule with the lock held, so a spinlock isn't sufficient. + + (*) Pin/Unpin object [optional]. + + int (*pin_object)(struct fscache_object *object) + void (*unpin_object)(struct fscache_object *object) + + These methods are used to pin an object into the cache. Once pinned an + object cannot be reclaimed to make space. Return -ENOSPC if there's not + enough space in the cache to permit this. + + (*) Update object [mandatory]. + + int (*update_object)(struct fscache_object *object) + + This is called to update the index entry for the specified object. The new + information should be in object->cookie->netfs_data. This can be obtained + by calling object->cookie->def->get_aux()/get_attr(). + + (*) Release object reference [mandatory]. + + void (*put_object)(struct fscache_object *object) + + This method is used to discard a reference to an object. The object may + be destroyed when all the references held by FS-Cache are released. + + (*) Synchronise a cache [mandatory]. + + void (*sync)(struct fscache_cache *cache) + + This is called to ask the backend to synchronise a cache with its backing + device. + + (*) Dissociate a cache [mandatory]. + + void (*dissociate_pages)(struct fscache_cache *cache) + + This is called to ask a cache to perform any page dissociations as part of + cache withdrawal. + + (*) Set the data size on a cache file [mandatory]. + + int (*set_i_size)(struct fscache_object *object, loff_t i_size); + + This is called to indicate to the cache the maximum size a file may + reach. The cache may use this to reserve space on the cache. It may also + return -ENOBUFS to indicate that insufficient space is available to expand + the metadata used to track the data. It should return 0 if successful or + -ENOMEM or -EIO on error. + + (*) Reserve cache space for an object's data [optional]. + + int (*reserve_space)(struct fscache_object *object, loff_t size); + + This is called to request that cache space be reserved to hold the data + for an object and the metadata used to track it. Zero size should be taken + as request to cancel a reservation. + + This should return 0 if successful, -ENOSPC if there isn't enough space + available, or -ENOMEM or -EIO on other errors. + + The reservation may exceed the size of the object, thus permitting future + expansion. If the amount of space consumed by an object would exceed the + reservation, it's permitted to refuse requests to allocate pages, but not + required. An object may be pruned down to its reservation size if larger + than that already. + + (*) Request page be read from cache [mandatory]. + + int (*read_or_alloc_page)(struct fscache_object *object, + struct page *page, + fscache_rw_complete_t end_io_func, + void *end_io_data, + gfp_t gfp) + + This is called to attempt to read a netfs page from the cache, or to + reserve a backing block if not. FS-Cache will have done as much checking + as it can before calling, but most of the work belongs to the backend. + + If there's no page in the cache, then -ENODATA should be returned if the + backend managed to reserve a backing block; -ENOBUFS, -ENOMEM or -EIO if + it didn't. + + If there is a page in the cache, then a read operation should be queued + and 0 returned. When the read finishes, end_io_func() should be called + with the following arguments: + + (*end_io_func)(object->cookie->netfs_data, + page, + end_io_data, + error); + + The mark_pages_cached() cookie operation should be called for the page if + any cache metadata is retained. This will indicate to the netfs that the + page needs explicit uncaching. This operation takes a pagevec, thus + allowing several pages to be marked at once. + + (*) Request pages be read from cache [mandatory]. + + int (*read_or_alloc_pages)(struct fscache_object *object, + struct address_space *mapping, + struct list_head *pages, + unsigned *nr_pages, + fscache_rw_complete_t end_io_func, + void *end_io_data, + gfp_t gfp) + + This is like the previous operation, except it will be handed a list of + pages instead of one page. Any pages on which a read operation is started + must be added to the page cache for the specified mapping and also to the + LRU. Such pages must also be removed from the pages list and nr_pages + decremented per page. + + If there was an error such as -ENOMEM, then that should be returned; else + if one or more pages couldn't be read or allocated, then -ENOBUFS should + be returned; else if one or more pages couldn't be read, then -ENODATA + should be returned. If all the pages are dispatched then 0 should be + returned. + + (*) Request page be allocated in the cache [mandatory]. + + int (*allocate_page)(struct fscache_object *object, + struct page *page, + gfp_t gfp) + + This is like read_or_alloc_page(), except that it shouldn't read from the + cache, even if there's data there that could be retrieved. It should, + however, set up any internal metadata required such that write_page() can + write to the cache. + + If there's no backing block available, then -ENOBUFS should be returned + (or -ENOMEM or -EIO if there were other problems). If a block is + successfully allocated, then the netfs page should be marked and 0 + returned. + + (*) Request page be written to cache [mandatory]. + + int (*write_page)(struct fscache_object *object, + struct page *page, + fscache_rw_complete_t end_io_func, + void *end_io_data, + gfp_t gfp) + + This is called to write from a page on which there was a previously + successful read_or_alloc_page() call. FS-Cache filters out pages that + don't have mappings. + + If there's no backing block available, then -ENOBUFS should be returned + (or -ENOMEM or -EIO if there were other problems). + + If the write operation could be queued, then 0 should be returned. When + the write completes, end_io_func() should be called with the following + arguments: + + (*end_io_func)(object->cookie->netfs_data, + page, + end_io_data, + error); + + (*) Discard retained per-page metadata [mandatory]. + + void (*uncache_pages)(struct fscache_object *object, + struct pagevec *pagevec) + + This is called when one or more netfs pages are being evicted from the + pagecache. The cache backend should tear down any internal representation + or tracking it maintains. --- /dev/null 2006-03-18 10:17:16.106812576 -0500 +++ linux-2.6.16.noarch/Documentation/filesystems/caching/fscache.txt 2006-03-27 09:49:31.000000000 -0500 @@ -0,0 +1,150 @@ + ========================== + General Filesystem Caching + ========================== + +======== +OVERVIEW +======== + +This facility is a general purpose cache for network filesystems, though it +could be used for caching other things such as ISO9660 filesystems too. + +FS-Cache mediates between cache backends (such as CacheFS) and network +filesystems: + + +---------+ + | | +-----------+ + | NFS |--+ | | + | | | +-->| CacheFS | + +---------+ | +----------+ | | /dev/hda5 | + | | | | +-----------+ + +---------+ +-->| | | + | | | |--+ +-------------+ + | AFS |----->| FS-Cache | | | + | | | |----->| Cache Files | + +---------+ +-->| | | /var/cache | + | | |--+ +-------------+ + +---------+ | +----------+ | + | | | | +-------------+ + | ISOFS |--+ | | | + | | +-->| ReiserCache | + +---------+ | / | + +-------------+ + +FS-Cache does not follow the idea of completely loading every netfs file +opened in its entirety into a cache before permitting it to be accessed and +then serving the pages out of that cache rather than the netfs inode because: + + (1) It must be practical to operate without a cache. + + (2) The size of any accessible file must not be limited to the size of the + cache. + + (3) The combined size of all opened files (this includes mapped libraries) + must not be limited to the size of the cache. + + (4) The user should not be forced to download an entire file just to do a + one-off access of a small portion of it (such as might be done with the + "file" program). + +It instead serves the cache out in PAGE_SIZE chunks as and when requested by +the netfs('s) using it. + + +FS-Cache provides the following facilities: + + (1) More than one cache can be used at once. Caches can be selected explicitly + by use of tags. + + (2) Caches can be added / removed at any time. + + (3) The netfs is provided with an interface that allows either party to + withdraw caching facilities from a file (required for (2)). + + (4) The interface to the netfs returns as few errors as possible, preferring + rather to let the netfs remain oblivious. + + (5) Cookies are used to represent indexes, files and other objects to the + netfs. The simplest cookie is just a NULL pointer - indicating nothing + cached there. + + (6) The netfs is allowed to propose - dynamically - any index hierarchy it + desires, though it must be aware that the index search function is + recursive, stack space is limited, and indexes can only be children of + indexes. + + (7) Data I/O is done direct to and from the netfs's pages. The netfs indicates + that page A is at index B of the data-file represented by cookie C, and + that it should be read or written. The cache backend may or may not start + I/O on that page, but if it does, a netfs callback will be invoked to + indicate completion. The I/O may be either synchronous or asynchronous. + + (8) Cookies can be "retired" upon release. At this point FS-Cache will mark + them as obsolete and the index hierarchy rooted at that point will get + recycled. + + (9) The netfs provides a "match" function for index searches. In addition to + saying whether a match was made or not, this can also specify that an + entry should be updated or deleted. + + +FS-Cache maintains a virtual indexing tree in which all indexes, files, objects +and pages are kept. Bits of this tree may actually reside in one or more +caches. + + FSDEF + | + +------------------------------------+ + | | + NFS AFS + | | + +--------------------------+ +-----------+ + | | | | + homedir mirror afs.org redhat.com + | | | + +------------+ +---------------+ +----------+ + | | | | | | + 00001 00002 00007 00125 vol00001 vol00002 + | | | | | + +---+---+ +-----+ +---+ +------+------+ +-----+----+ + | | | | | | | | | | | | | +PG0 PG1 PG2 PG0 XATTR PG0 PG1 DIRENT DIRENT DIRENT R/W R/O Bak + | | + PG0 +-------+ + | | + 00001 00003 + | + +---+---+ + | | | + PG0 PG1 PG2 + +In the example above, you can see two netfs's being backed: NFS and AFS. These +have different index hierarchies: + + (*) The NFS primary index contains per-server indexes. Each server index is + indexed by NFS file handles to get data file objects. Each data file + objects can have an array of pages, but may also have further child + objects, such as extended attributes and directory entries. Extended + attribute objects themselves have page-array contents. + + (*) The AFS primary index contains per-cell indexes. Each cell index contains + per-logical-volume indexes. Each of volume index contains up to three + indexes for the read-write, read-only and backup mirrors of those + volumes. Each of these contains vnode data file objects, each of which + contains an array of pages. + +The very top index is the FS-Cache master index in which individual netfs's +have entries. + +Any index object may reside in more than one cache, provided it only has index +children. Any index with non-index object children will be assumed to only +reside in one cache. + + +The netfs API to FS-Cache can be found in: + + Documentation/filesystems/caching/netfs-api.txt + +The cache backend API to FS-Cache can be found in: + + Documentation/filesystems/caching/backend-api.txt --- /dev/null 2006-03-18 10:17:16.106812576 -0500 +++ linux-2.6.16.noarch/Documentation/filesystems/caching/netfs-api.txt 2006-03-27 09:49:31.000000000 -0500 @@ -0,0 +1,726 @@ + =============================== + FS-CACHE NETWORK FILESYSTEM API + =============================== + +There's an API by which a network filesystem can make use of the FS-Cache +facilities. This is based around a number of principles: + + (1) Caches can store a number of different object types. There are two main + object types: indexes and files. The first is a special type used by + FS-Cache to make finding objects faster and to make retiring of groups of + objects easier. + + (2) Every index, file or other object is represented by a cookie. This cookie + may or may not have anything associated with it, but the netfs doesn't + need to care. + + (3) Barring the top-level index (one entry per cached netfs), the index + hierarchy for each netfs is structured according the whim of the netfs. + +This API is declared in . + +This document contains the following sections: + + (1) Network filesystem definition + (2) Index definition + (3) Object definition + (4) Network filesystem (un)registration + (5) Cache tag lookup + (6) Index registration + (7) Data file registration + (8) Miscellaneous object registration + (9) Setting the data file size + (10) Page alloc/read/write + (11) Page uncaching + (12) Index and data file update + (13) Miscellaneous cookie operations + (14) Cookie unregistration + (15) Index and data file invalidation + + +============================= +NETWORK FILESYSTEM DEFINITION +============================= + +FS-Cache needs a description of the network filesystem. This is specified using +a record of the following structure: + + struct fscache_netfs { + uint32_t version; + const char *name; + struct fscache_netfs_operations *ops; + struct fscache_cookie *primary_index; + ... + }; + +This first three fields should be filled in before registration, and the fourth +will be filled in by the registration function; any other fields should just be +ignored and are for internal use only. + +The fields are: + + (1) The name of the netfs (used as the key in the toplevel index). + + (2) The version of the netfs (if the name matches but the version doesn't, the + entire in-cache hierarchy for this netfs will be scrapped and begun + afresh). + + (3) The operations table is defined as follows: + + struct fscache_netfs_operations { + }; + + Currently there aren't any functions here. + + (4) The cookie representing the primary index will be allocated according to + another parameter passed into the registration function. + +For example, kAFS (linux/fs/afs/) uses the following definitions to describe +itself: + + static struct fscache_netfs_operations afs_cache_ops = { + }; + + struct fscache_netfs afs_cache_netfs = { + .version = 0, + .name = "afs", + .ops = &afs_cache_ops, + }; + + +================ +INDEX DEFINITION +================ + +Indexes are used for two purposes: + + (1) To aid the finding of a file based on a series of keys (such as AFS's + "cell", "volume ID", "vnode ID"). + + (2) To make it easier to discard a subset of all the files cached based around + a particular key - for instance to mirror the removal of an AFS volume. + +However, since it's unlikely that any two netfs's are going to want to define +their index hierarchies in quite the same way, FS-Cache tries to impose as few +restraints as possible on how an index is structured and where it is placed in +the tree. The netfs can even mix indexes and data files at the same level, but +it's not recommended. + +Each index entry consists of a key of indeterminate length plus some auxilliary +data, also of indeterminate length. + +There are some limits on indexes: + + (1) Any index containing non-index objects should be restricted to a single + cache. Any such objects created within an index will be created in the + first cache only. The cache in which an index is created can be controlled + by cache tags (see below). + + (2) The entry data must be atomically journallable, so it is limited to about + 400 bytes at present. At least 400 bytes will be available. + + (3) The depth of the index tree should be judged with care as the search + function is recursive. Too many layers will run the kernel out of stack. + + +================= +OBJECT DEFINITION +================= + +To define an object, a structure of the following type should be filled out: + + struct fscache_object_def + { + uint8_t name[16]; + uint8_t type; + + struct fscache_cache_tag *(*select_cache)( + const void *parent_netfs_data, + const void *cookie_netfs_data); + + uint16_t (*get_key)(const void *cookie_netfs_data, + void *buffer, + uint16_t bufmax); + + void (*get_attr)(const void *cookie_netfs_data, + uint64_t *size); + + uint16_t (*get_aux)(const void *cookie_netfs_data, + void *buffer, + uint16_t bufmax); + + fscache_checkaux_t (*check_aux)(void *cookie_netfs_data, + const void *data, + uint16_t datalen); + + void (*mark_pages_cached)(void *cookie_netfs_data, + struct address_space *mapping, + struct pagevec *cached_pvec); + + void (*now_uncached)(void *cookie_netfs_data); + }; + +This has the following fields: + + (1) The type of the object [mandatory]. + + This is one of the following values: + + (*) FSCACHE_COOKIE_TYPE_INDEX + + This defines an index, which is a special FS-Cache type. + + (*) FSCACHE_COOKIE_TYPE_DATAFILE + + This defines an ordinary data file. + + (*) Any other value between 2 and 255 + + This defines an extraordinary object such as an XATTR. + + (2) The name of the object type (NUL terminated unless all 16 chars are used) + [optional]. + + (3) A function to select the cache in which to store an index [optional]. + + This function is invoked when an index needs to be instantiated in a cache + during the instantiation of a non-index object. Only the immediate index + parent for the non-index object will be queried. Any indexes above that in + the hierarchy may be stored in multiple caches. This function does not + need to be supplied for any non-index object or any index that will only + have index children. + + If this function is not supplied or if it returns NULL then the first + cache in the parent's list will be chosed, or failing that, the first + cache in the master list. + + (4) A function to retrieve an object's key from the netfs [mandatory]. + + This function will be called with the netfs data that was passed to the + cookie acquisition function and the maximum length of key data that it may + provide. It should write the required key data into the given buffer and + return the quantity it wrote. + + (5) A function to retrieve attribute data from the netfs [optional]. + + This function will be called with the netfs data that was passed to the + cookie acquisition function. It should return the size of the file if this + is a data file. The size may be used to govern how much cache must be + reserved for this file in the cache. + + If the function is absent, a file size of 0 is assumed. + + (6) A function to retrieve auxilliary data from the netfs [optional]. + + This function will be called with the netfs data that was passed to the + cookie acquisition function and the maximum length of auxilliary data that + it may provide. It should write the auxilliary data into the given buffer + and return the quantity it wrote. + + If this function is absent, the auxilliary data length will be set to 0. + + The length of the auxilliary data buffer may be dependent on the key + length. A netfs mustn't rely on being able to provide more than 400 bytes + for both. + + (7) A function to check the auxilliary data [optional]. + + This function will be called to check that a match found in the cache for + this object is valid. For instance with AFS it could check the auxilliary + data against the data version number returned by the server to determine + whether the index entry in a cache is still valid. + + If this function is absent, it will be assumed that matching objects in a + cache are always valid. + + If present, the function should return one of the following values: + + (*) FSCACHE_CHECKAUX_OKAY - the entry is okay as is + (*) FSCACHE_CHECKAUX_NEEDS_UPDATE - the entry requires update + (*) FSCACHE_CHECKAUX_OBSOLETE - the entry should be deleted + + This function can also be used to extract data from the auxilliary data in + the cache and copy it into the netfs's structures. + + (8) A function to mark a page as retaining cache metadata [mandatory]. + + This is called by the cache to indicate that it is retaining in-memory + information for this page and that the netfs should uncache the page when + it has finished. This does not indicate whether there's data on the disk + or not. Note that several pages at once may be presented for marking. + + kAFS and NFS use the PG_private bit on the page structure for this, but + that may not be appropriate in all cases. + + This function is not required for indexes as they're not permitted data. + + (9) A function to unmark all the pages retaining cache metadata [mandatory]. + + This is called by FS-Cache to indicate that a backing store is being + unbound from a cookie and that all the marks on the pages should be + cleared to prevent confusion. Note that the cache will have torn down all + its tracking information so that the pages don't need to be explicitly + uncached. + + This function is not required for indexes as they're not permitted data. + + +=================================== +NETWORK FILESYSTEM (UN)REGISTRATION +=================================== + +The first step is to declare the network filesystem to the cache. This also +involves specifying the layout of the primary index (for AFS, this would be the +"cell" level). + +The registration function is: + + int fscache_register_netfs(struct fscache_netfs *netfs); + +It just takes a pointer to the netfs definition. It returns 0 or an error as +appropriate. + +For kAFS, registration is done as follows: + + ret = fscache_register_netfs(&afs_cache_netfs); + +The last step is, of course, unregistration: + + void fscache_unregister_netfs(struct fscache_netfs *netfs); + + +================ +CACHE TAG LOOKUP +================ + +FS-Cache permits the use of more than one cache. To permit particular index +subtrees to be bound to particular caches, the second step is to look up cache +representation tags. This step is optional; it can be left entirely up to +FS-Cache as to which cache should be used. The problem with doing that is that +FS-Cache will always pick the first cache that was registered. + +To get the representation for a named tag: + + struct fscache_cache_tag *fscache_lookup_cache_tag(const char *name); + +This takes a text string as the name and returns a representation of a tag. It +will never return an error. It may return a dummy tag, however, if it runs out +of memory; this will inhibit caching with this tag. + +Any representation so obtained must be released by passing it to this function: + + void fscache_release_cache_tag(struct fscache_cache_tag *tag); + +The tag will be retrieved by FS-Cache when it calls the object definition +operation select_cache(). + + +================== +INDEX REGISTRATION +================== + +The third step is to inform FS-Cache about part of an index hierarchy that can +be used to locate files. This is done by requesting a cookie for each index in +the path to the file: + + struct fscache_cookie * + fscache_acquire_cookie(struct fscache_cookie *parent, + struct fscache_object_def *def, + void *netfs_data); + +This function creates an index entry in the index represented by parent, +filling in the index entry by calling the operations pointed to by def. + +Note that this function never returns an error - all errors are handled +internally. It may also return FSCACHE_NEGATIVE_COOKIE. It is quite acceptable +to pass this token back to this function as the parent to another acquisition +(or even to the relinquish cookie, read page and write page functions - see +below). + +Note also that no indexes are actually created in a cache until a non-index +object needs to be created somewhere down the hierarchy. Furthermore, an index +may be created in several different caches independently at different +times. This is all handled transparently, and the netfs doesn't see any of it. + +For example, with AFS, a cell would be added to the primary index. This index +entry would have a dependent inode containing a volume location index for the +volume mappings within this cell: + + cell->cache = + fscache_acquire_cookie(afs_cache_netfs.primary_index, + &afs_cell_cache_index_def, + cell); + +Then when a volume location was accessed, it would be entered into the cell's +index and an inode would be allocated that acts as a volume type and hash chain +combination: + + vlocation->cache = + fscache_acquire_cookie(cell->cache, + &afs_vlocation_cache_index_def, + vlocation); + +And then a particular flavour of volume (R/O for example) could be added to +that index, creating another index for vnodes (AFS inode equivalents): + + volume->cache = + fscache_acquire_cookie(vlocation->cache, + &afs_volume_cache_index_def, + volume); + + +====================== +DATA FILE REGISTRATION +====================== + +The fourth step is to request a data file be created in the cache. This is +identical to index cookie acquisition. The only difference is that the type in +the object definition should be something other than index type. + + vnode->cache = + fscache_acquire_cookie(volume->cache, + &afs_vnode_cache_object_def, + vnode); + + +================================= +MISCELLANEOUS OBJECT REGISTRATION +================================= + +An optional step is to request an object of miscellaneous type be created in +the cache. This is almost identical to index cookie acquisition. The only +difference is that the type in the object definition should be something other +than index type. Whilst the parent object could be an index, it's more likely +it would be some other type of object such as a data file. + + xattr->cache = + fscache_acquire_cookie(vnode->cache, + &afs_xattr_cache_object_def, + xattr); + +Miscellaneous objects might be used to store extended attributes or directory +entries for example. + + +========================== +SETTING THE DATA FILE SIZE +========================== + +The fifth step is to set the size of the file. This doesn't automatically +reserve any space in the cache, but permits the cache to adjust its metadata +for data tracking appropriately: + + int fscache_set_i_size(struct fscache_cookie *cookie, loff_t i_size); + +The cache will return -ENOBUFS if there is no backing cache or if there is no +space to allocate any extra metadata required in the cache. + +Note that attempts to read or write data pages in the cache over this size may +be rebuffed with -ENOBUFS. + + +===================== +PAGE READ/ALLOC/WRITE +===================== + +And the sixth step is to store and retrieve pages in the cache. There are three +functions that are used to do this. + +Note: + + (1) A page should not be re-read or re-allocated without uncaching it first. + + (2) A read or allocated page must be uncached when the netfs page is released + from the pagecache. + + (3) A page should only be written to the cache if previous read or allocated. + +This permits the cache to maintain its page tracking in proper order. + + +PAGE READ +--------- + +Firstly, the netfs should ask FS-Cache to examine the caches and read the +contents cached for a particular page of a particular file if present, or else +allocate space to store the contents if not: + + typedef + void (*fscache_rw_complete_t)(void *cookie_data, + struct page *page, + void *end_io_data, + int error); + + int fscache_read_or_alloc_page(struct fscache_cookie *cookie, + struct page *page, + fscache_rw_complete_t end_io_func, + void *end_io_data, + gfp_t gfp); + +The cookie argument must specify a cookie for an object that isn't an index, +the page specified will have the data loaded into it (and is also used to +specify the page number), and the gfp argument is used to control how any +memory allocations made are satisfied. + +If the cookie indicates the inode is not cached: + + (1) The function will return -ENOBUFS. + +Else if there's a copy of the page resident in the cache: + + (1) The mark_pages_cached() cookie operation will be called on that page. + + (2) The function will submit a request to read the data from the cache's + backing device directly into the page specified. + + (3) The function will return 0. + + (4) When the read is complete, end_io_func() will be invoked with: + + (*) The netfs data supplied when the cookie was created. + + (*) The page descriptor. + + (*) The end_io_data argument passed to the above function. + + (*) An argument that's 0 on success or negative for an error code. + + If an error occurs, it should be assumed that the page contains no usable + data. + +Otherwise, if there's not a copy available in cache, but the cache may be able +to store the page: + + (1) The mark_pages_cached() cookie operation will be called on that page. + + (2) A block may be reserved in the cache and attached to the object at the + appropriate place. + + (3) The function will return -ENODATA. + +This function may also return -ENOMEM or -EINTR, in which case it won't have +read any data from the cache. + + +PAGE ALLOCATE +------------- + +Alternatively, if there's not expected to be any data in the cache for a page +because the file has been extended, a block can simply be allocated instead: + + int fscache_alloc_page(struct fscache_cookie *cookie, + struct page *page, + gfp_t gfp); + +This is similar to the fscache_read_or_alloc_page() function, except that it +never reads from the cache. It will return 0 if a block has been allocated, +rather than -ENODATA as the other would. One or the other must be performed +before writing to the cache. + +The mark_pages_cached() cookie operation will be called on the page if +successful. + + +PAGE WRITE +---------- + +Secondly, if the netfs changes the contents of the page (either due to an +initial download or if a user performs a write), then the page should be +written back to the cache: + + int fscache_write_page(struct fscache_cookie *cookie, + struct page *page, + fscache_rw_complete_t end_io_func, + void *end_io_data, + gfp_t gfp); + +The cookie argument must specify a data file cookie, the page specified should +contain the data to be written (and is also used to specify the page number), +and the gfp argument is used to control how any memory allocations made are +satisfied. + +The page must have first been read or allocated successfully and must not have +been uncached before writing is performed. + +If the cookie indicates the inode is not cached then: + + (1) The function will return -ENOBUFS. + +Else if space can be allocated in the cache to hold this page: + + (1) The function will submit a request to write the data to cache's backing + device directly from the page specified. + + (2) The function will return 0. + + (3) When the write is complete the end_io_func() will be invoked with: + + (*) The netfs data supplied when the cookie was created. + + (*) The page descriptor. + + (*) The end_io_data argument passed to the function. + + (*) An argument that's 0 on success or negative for an error. + + If an error occurs, it can be assumed that the page has not been written + to the cache, and that either there's a block containing the old data or + no block at all in the cache. + +Else if there's no space available in the cache, -ENOBUFS will be returned. + + +MULTIPLE PAGE READ +------------------ + +A facility is provided to read several pages at once, as requested by the +readpages() address space operation: + + int fscache_read_or_alloc_pages(struct fscache_cookie *cookie, + struct address_space *mapping, + struct list_head *pages, + int *nr_pages, + fscache_rw_complete_t end_io_func, + void *end_io_data, + gfp_t gfp); + +This works in a similar way to fscache_read_or_alloc_page(), except: + + (1) Any page it can retrieve data for is removed from pages and nr_pages and + dispatched for reading to the disk. Reads of adjacent pages on disk may be + merged for greater efficiency. + + (2) The mark_pages_cached() cookie operation will be called on several pages + at once if they're being read or allocated. + + (3) If there was an general error, then that error will be returned. + + Else if some pages couldn't be allocated or read, then -ENOBUFS will be + returned. + + Else if some pages couldn't be read but were allocated, then -ENODATA will + be returned. + + Otherwise, if all pages had reads dispatched, then 0 will be returned, the + list will be empty and *nr_pages will be 0. + + (4) end_io_func will be called once for each page being read as the reads + complete. + +Note that a return of -ENODATA, -ENOBUFS or any other error does not preclude +some of the pages being read and some being allocated. Those pages will have +been marked appropriately and will need uncaching. + + +============== +PAGE UNCACHING +============== + +To uncache a page, this function should be called: + + void fscache_uncache_page(struct fscache_cookie *cookie, + struct page *page); + +This function permits the cache to release any in-memory representation it +might be holding for this netfs page. This function must be called once for +each page on which the read or write page functions above have been called to +make sure the cache's in-memory tracking information gets torn down. + +Note that pages can't be explicitly deleted from the a data file. The whole +data file must be retired (see the relinquish cookie function below). + +Furthermore, note that this does not cancel the asynchronous read or write +operation started by the read/alloc and write functions. + +There is another unbinding operation similar to the above that takes a set of +pages to unbind in one go: + + void fscache_uncache_pagevec(struct fscache_cookie *cookie, + struct pagevec *pagevec); + + +========================== +INDEX AND DATA FILE UPDATE +========================== + +To request an update of the index data for an index or other object, the +following function should be called: + + void fscache_update_cookie(struct fscache_cookie *cookie); + +This function will refer back to the netfs_data pointer stored in the cookie by +the acquisition function to obtain the data to write into each revised index +entry. The update method in the parent index definition will be called to +transfer the data. + +Note that partial updates may happen automatically at other times, such as when +data blocks are added to a data file object. + + +=============================== +MISCELLANEOUS COOKIE OPERATIONS +=============================== + +There are a number of operations that can be used to control cookies: + + (*) Cookie pinning: + + int fscache_pin_cookie(struct fscache_cookie *cookie); + void fscache_unpin_cookie(struct fscache_cookie *cookie); + + These operations permit data cookies to be pinned into the cache and to + have the pinning removed. They are not permitted on index cookies. + + The pinning function will return 0 if successful, -ENOBUFS in the cookie + isn't backed by a cache, -EOPNOTSUPP if the cache doesn't support pinning, + -ENOSPC if there isn't enough space to honour the operation, -ENOMEM or + -EIO if there's any other problem. + + (*) Data space reservation: + + int fscache_reserve_space(struct fscache_cookie *cookie, loff_t size); + + This permits a netfs to request cache space be reserved to store up to the + given amount of a file. It is permitted to ask for more than the current + size of the file to allow for future file expansion. + + If size is given as zero then the reservation will be cancelled. + + The function will return 0 if successful, -ENOBUFS in the cookie isn't + backed by a cache, -EOPNOTSUPP if the cache doesn't support reservations, + -ENOSPC if there isn't enough space to honour the operation, -ENOMEM or + -EIO if there's any other problem. + + Note that this doesn't pin an object in a cache; it can still be culled to + make space if it's not in use. + + +===================== +COOKIE UNREGISTRATION +===================== + +To get rid of a cookie, this function should be called. + + void fscache_relinquish_cookie(struct fscache_cookie *cookie, + int retire); + +If retire is non-zero, then the object will be marked for recycling, and all +copies of it will be removed from all active caches in which it is present. Not +only that but all child objects will also be retired. + +If retire is zero, then the object may be available again when next the +acquisition function is called. Retirement here will overrule the pinning on a +cookie. + +One very important note - relinquish must NOT be called for a cookie unless all +the cookies for "child" indexes, objects and pages have been relinquished +first. + + +================================ +INDEX AND DATA FILE INVALIDATION +================================ + +There is no direct way to invalidate an index subtree or a data file. To do +this, the caller should relinquish and retire the cookie they have, and then +acquire a new one. --- linux-2.6.16.noarch/fs/Kconfig.fscache 2006-03-27 09:48:39.000000000 -0500 +++ linux-2.6.16.noarch/fs/Kconfig 2006-03-27 09:49:31.000000000 -0500 @@ -508,6 +508,21 @@ config FUSE_FS If you want to develop a userspace FS, or if you want to use a filesystem based on FUSE, answer Y or M. +menu "Caches" + +config FSCACHE + tristate "General filesystem cache manager" + depends on EXPERIMENTAL + help + This option enables a generic filesystem caching manager that can be + used by various network and other filesystems to cache data + locally. Different sorts of caches can be plugged in, depending on the + resources available. + + See Documentation/filesystems/caching/fscache.txt for more information. + +endmenu + menu "CD-ROM/DVD Filesystems" config ISO9660_FS --- linux-2.6.16.noarch/fs/Makefile.fscache 2006-03-27 09:48:39.000000000 -0500 +++ linux-2.6.16.noarch/fs/Makefile 2006-03-27 09:49:53.000000000 -0500 @@ -50,6 +50,7 @@ obj-y += devpts/ obj-$(CONFIG_PROFILING) += dcookies.o # Do not add any filesystems before this line +obj-$(CONFIG_FSCACHE) += fscache/ obj-$(CONFIG_REISERFS_FS) += reiserfs/ obj-$(CONFIG_EXT3_FS) += ext3/ # Before ext2 so root fs can be ext3 obj-$(CONFIG_JBD) += jbd/ --- /dev/null 2006-03-18 10:17:16.106812576 -0500 +++ linux-2.6.16.noarch/fs/fscache/Makefile 2006-03-27 09:49:31.000000000 -0500 @@ -0,0 +1,13 @@ +# +# Makefile for general filesystem caching code +# + +#CFLAGS += -finstrument-functions + +fscache-objs := \ + cookie.o \ + fsdef.o \ + main.o \ + page.o + +obj-$(CONFIG_FSCACHE) := fscache.o --- /dev/null 2006-03-18 10:17:16.106812576 -0500 +++ linux-2.6.16.noarch/fs/fscache/cookie.c 2006-03-27 09:49:31.000000000 -0500 @@ -0,0 +1,1030 @@ +/* cookie.c: general filesystem cache cookie management + * + * Copyright (C) 2004-5 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. + */ + +#include +#include "fscache-int.h" + +static LIST_HEAD(fscache_cache_tag_list); +static LIST_HEAD(fscache_cache_list); +static LIST_HEAD(fscache_netfs_list); +static DECLARE_RWSEM(fscache_addremove_sem); +static struct fscache_cache_tag fscache_nomem_tag; + +kmem_cache_t *fscache_cookie_jar; + +static void fscache_withdraw_object(struct fscache_cache *cache, + struct fscache_object *object); + +static void __fscache_cookie_put(struct fscache_cookie *cookie); + +static inline void fscache_cookie_put(struct fscache_cookie *cookie) +{ +#ifdef CONFIG_DEBUG_SLAB + BUG_ON((atomic_read(&cookie->usage) & 0xffff0000) == 0x6b6b0000); +#endif + + BUG_ON(atomic_read(&cookie->usage) <= 0); + + if (atomic_dec_and_test(&cookie->usage)) + __fscache_cookie_put(cookie); + +} + +/*****************************************************************************/ +/* + * look up a cache tag + */ +struct fscache_cache_tag *__fscache_lookup_cache_tag(const char *name) +{ + struct fscache_cache_tag *tag, *xtag; + + /* firstly check for the existence of the tag under read lock */ + down_read(&fscache_addremove_sem); + + list_for_each_entry(tag, &fscache_cache_tag_list, link) { + if (strcmp(tag->name, name) == 0) { + atomic_inc(&tag->usage); + up_read(&fscache_addremove_sem); + return tag; + } + } + + up_read(&fscache_addremove_sem); + + /* the tag does not exist - create a candidate */ + xtag = kmalloc(sizeof(*tag) + strlen(name) + 1, GFP_KERNEL); + if (!xtag) { + /* return a dummy tag if out of memory */ + up_read(&fscache_addremove_sem); + return &fscache_nomem_tag; + } + + atomic_set(&tag->usage, 1); + strcpy(tag->name, name); + + /* write lock, search again and add if still not present */ + down_write(&fscache_addremove_sem); + + list_for_each_entry(tag, &fscache_cache_tag_list, link) { + if (strcmp(tag->name, name) == 0) { + atomic_inc(&tag->usage); + up_write(&fscache_addremove_sem); + kfree(xtag); + return tag; + } + } + + list_add_tail(&xtag->link, &fscache_cache_tag_list); + up_write(&fscache_addremove_sem); + return xtag; + +} /* end __fscache_lookup_cache_tag() */ + +/*****************************************************************************/ +/* + * release a reference to a cache tag + */ +void __fscache_release_cache_tag(struct fscache_cache_tag *tag) +{ + if (tag != &fscache_nomem_tag) { + down_write(&fscache_addremove_sem); + + if (atomic_dec_and_test(&tag->usage)) + list_del_init(&tag->link); + else + tag = NULL; + + up_write(&fscache_addremove_sem); + + kfree(tag); + } + +} /* end __fscache_release_cache_tag() */ + +/*****************************************************************************/ +/* + * register a network filesystem for caching + */ +int __fscache_register_netfs(struct fscache_netfs *netfs) +{ + struct fscache_netfs *ptr; + int ret; + + _enter("{%s}", netfs->name); + + INIT_LIST_HEAD(&netfs->link); + + /* allocate a cookie for the primary index */ + netfs->primary_index = + kmem_cache_alloc(fscache_cookie_jar, SLAB_KERNEL); + + if (!netfs->primary_index) { + _leave(" = -ENOMEM"); + return -ENOMEM; + } + + /* initialise the primary index cookie */ + memset(netfs->primary_index, 0, sizeof(*netfs->primary_index)); + + atomic_set(&netfs->primary_index->usage, 1); + atomic_set(&netfs->primary_index->children, 0); + + netfs->primary_index->def = &fscache_fsdef_netfs_def; + netfs->primary_index->parent = &fscache_fsdef_index; + netfs->primary_index->netfs = netfs; + netfs->primary_index->netfs_data = netfs; + + atomic_inc(&netfs->primary_index->parent->usage); + atomic_inc(&netfs->primary_index->parent->children); + + init_rwsem(&netfs->primary_index->sem); + INIT_HLIST_HEAD(&netfs->primary_index->backing_objects); + + /* check the netfs type is not already present */ + down_write(&fscache_addremove_sem); + + ret = -EEXIST; + list_for_each_entry(ptr, &fscache_netfs_list, link) { + if (strcmp(ptr->name, netfs->name) == 0) + goto already_registered; + } + + list_add(&netfs->link, &fscache_netfs_list); + ret = 0; + + printk("FS-Cache: netfs '%s' registered for caching\n", netfs->name); + +already_registered: + up_write(&fscache_addremove_sem); + + if (ret < 0) { + netfs->primary_index->parent = NULL; + __fscache_cookie_put(netfs->primary_index); + netfs->primary_index = NULL; + } + + _leave(" = %d", ret); + return ret; + +} /* end __fscache_register_netfs() */ + +EXPORT_SYMBOL(__fscache_register_netfs); + +/*****************************************************************************/ +/* + * unregister a network filesystem from the cache + * - all cookies must have been released first + */ +void __fscache_unregister_netfs(struct fscache_netfs *netfs) +{ + _enter("{%s.%u}", netfs->name, netfs->version); + + down_write(&fscache_addremove_sem); + + list_del(&netfs->link); + fscache_relinquish_cookie(netfs->primary_index, 0); + + up_write(&fscache_addremove_sem); + + printk("FS-Cache: netfs '%s' unregistered from caching\n", + netfs->name); + + _leave(""); + +} /* end __fscache_unregister_netfs() */ + +EXPORT_SYMBOL(__fscache_unregister_netfs); + +/*****************************************************************************/ +/* + * initialise a cache record + */ +void fscache_init_cache(struct fscache_cache *cache, + struct fscache_cache_ops *ops, + const char *idfmt, + ...) +{ + va_list va; + + memset(cache, 0, sizeof(*cache)); + + cache->ops = ops; + + va_start(va, idfmt); + vsnprintf(cache->identifier, sizeof(cache->identifier), idfmt, va); + va_end(va); + + INIT_LIST_HEAD(&cache->link); + INIT_LIST_HEAD(&cache->object_list); + spin_lock_init(&cache->object_list_lock); + init_rwsem(&cache->withdrawal_sem); + +} /* end fscache_init_cache() */ + +EXPORT_SYMBOL(fscache_init_cache); + +/*****************************************************************************/ +/* + * declare a mounted cache as being open for business + */ +int fscache_add_cache(struct fscache_cache *cache, + struct fscache_object *ifsdef, + const char *tagname) +{ + struct fscache_cache_tag *tag; + + BUG_ON(!cache->ops); + BUG_ON(!ifsdef); + + if (!tagname) + tagname = cache->identifier; + + BUG_ON(!tagname[0]); + + _enter("{%s.%s},,%s", cache->ops->name, cache->identifier, tagname); + + if (!cache->ops->grab_object(ifsdef)) + BUG(); + + ifsdef->cookie = &fscache_fsdef_index; + ifsdef->cache = cache; + cache->fsdef = ifsdef; + + down_write(&fscache_addremove_sem); + + /* instantiate or allocate a cache tag */ + list_for_each_entry(tag, &fscache_cache_tag_list, link) { + if (strcmp(tag->name, tagname) == 0) { + if (tag->cache) { + printk(KERN_ERR + "FS-Cache: cache tag '%s' already in use\n", + tagname); + up_write(&fscache_addremove_sem); + return -EEXIST; + } + + atomic_inc(&tag->usage); + goto found_cache_tag; + } + } + + tag = kmalloc(sizeof(*tag) + strlen(tagname) + 1, GFP_KERNEL); + if (!tag) { + up_write(&fscache_addremove_sem); + return -ENOMEM; + } + + atomic_set(&tag->usage, 1); + strcpy(tag->name, tagname); + list_add_tail(&tag->link, &fscache_cache_tag_list); + +found_cache_tag: + tag->cache = cache; + cache->tag = tag; + + /* add the cache to the list */ + list_add(&cache->link, &fscache_cache_list); + + /* add the cache's netfs definition index object to the cache's + * list */ + spin_lock(&cache->object_list_lock); + list_add_tail(&ifsdef->cache_link, &cache->object_list); + spin_unlock(&cache->object_list_lock); + + /* add the cache's netfs definition index object to the top level index + * cookie as a known backing object */ + down_write(&fscache_fsdef_index.sem); + + hlist_add_head(&ifsdef->cookie_link, + &fscache_fsdef_index.backing_objects); + + atomic_inc(&fscache_fsdef_index.usage); + + /* done */ + up_write(&fscache_fsdef_index.sem); + up_write(&fscache_addremove_sem); + + printk(KERN_NOTICE + "FS-Cache: Cache \"%s\" added (type %s)\n", + cache->tag->name, cache->ops->name); + + _leave(" = 0 [%s]", cache->identifier); + return 0; + +} /* end fscache_add_cache() */ + +EXPORT_SYMBOL(fscache_add_cache); + +/*****************************************************************************/ +/* + * withdraw an unmounted cache from the active service + */ +void fscache_withdraw_cache(struct fscache_cache *cache) +{ + struct fscache_object *object; + + _enter(""); + + printk(KERN_NOTICE + "FS-Cache: Withdrawing cache \"%s\"\n", + cache->tag->name); + + /* make the cache unavailable for cookie acquisition */ + down_write(&cache->withdrawal_sem); + + down_write(&fscache_addremove_sem); + list_del_init(&cache->link); + cache->tag->cache = NULL; + up_write(&fscache_addremove_sem); + + /* mark all objects as being withdrawn */ + spin_lock(&cache->object_list_lock); + list_for_each_entry(object, &cache->object_list, cache_link) { + set_bit(FSCACHE_OBJECT_WITHDRAWN, &object->flags); + } + spin_unlock(&cache->object_list_lock); + + /* make sure all pages pinned by operations on behalf of the netfs are + * written to disc */ + cache->ops->sync_cache(cache); + + /* dissociate all the netfs pages backed by this cache from the block + * mappings in the cache */ + cache->ops->dissociate_pages(cache); + + /* we now have to destroy all the active objects pertaining to this + * cache */ + spin_lock(&cache->object_list_lock); + + while (!list_empty(&cache->object_list)) { + object = list_entry(cache->object_list.next, + struct fscache_object, cache_link); + list_del_init(&object->cache_link); + spin_unlock(&cache->object_list_lock); + + _debug("withdraw %p", object->cookie); + + /* we've extracted an active object from the tree - now dispose + * of it */ + fscache_withdraw_object(cache, object); + + spin_lock(&cache->object_list_lock); + } + + spin_unlock(&cache->object_list_lock); + + fscache_release_cache_tag(cache->tag); + cache->tag = NULL; + + _leave(""); + +} /* end fscache_withdraw_cache() */ + +EXPORT_SYMBOL(fscache_withdraw_cache); + +/*****************************************************************************/ +/* + * withdraw an object from active service at the behest of the cache + * - need break the links to a cached object cookie + * - called under two situations: + * (1) recycler decides to reclaim an in-use object + * (2) a cache is unmounted + * - have to take care as the cookie can be being relinquished by the netfs + * simultaneously + * - the active object is pinned by the caller holding a refcount on it + */ +static void fscache_withdraw_object(struct fscache_cache *cache, + struct fscache_object *object) +{ + struct fscache_cookie *cookie, *xcookie = NULL; + + _enter(",%p", object); + + /* first of all we have to break the links between the object and the + * cookie + * - we have to hold both semaphores BUT we have to get the cookie sem + * FIRST + */ + cache->ops->lock_object(object); + + cookie = object->cookie; + if (cookie) { + /* pin the cookie so that is doesn't escape */ + atomic_inc(&cookie->usage); + + /* re-order the locks to avoid deadlock */ + cache->ops->unlock_object(object); + down_write(&cookie->sem); + cache->ops->lock_object(object); + + /* erase references from the object to the cookie */ + hlist_del_init(&object->cookie_link); + + xcookie = object->cookie; + object->cookie = NULL; + + up_write(&cookie->sem); + } + + cache->ops->unlock_object(object); + + /* we've broken the links between cookie and object */ + if (xcookie) { + fscache_cookie_put(xcookie); + cache->ops->put_object(object); + } + + /* unpin the cookie */ + if (cookie) { + if (cookie->def && cookie->def->now_uncached) + cookie->def->now_uncached(cookie->netfs_data); + fscache_cookie_put(cookie); + } + + _leave(""); + +} /* end fscache_withdraw_object() */ + +/*****************************************************************************/ +/* + * select a cache on which to store an object + * - the cache addremove semaphore must be at least read-locked by the caller + * - the object will never be an index + */ +static struct fscache_cache *fscache_select_cache_for_object(struct fscache_cookie *cookie) +{ + struct fscache_cache_tag *tag; + struct fscache_object *object; + struct fscache_cache *cache; + + _enter(""); + + if (list_empty(&fscache_cache_list)) { + _leave(" = NULL [no cache]"); + return NULL; + } + + /* we check the parent to determine the cache to use */ + down_read(&cookie->parent->sem); + + /* the first in the parent's backing list should be the preferred + * cache */ + if (!hlist_empty(&cookie->parent->backing_objects)) { + object = hlist_entry(cookie->parent->backing_objects.first, + struct fscache_object, cookie_link); + + cache = object->cache; + up_read(&cookie->parent->sem); + _leave(" = %p [parent]", cache); + return cache; + } + + /* the parent is unbacked */ + if (cookie->parent->def->type != FSCACHE_COOKIE_TYPE_INDEX) { + /* parent not an index and is unbacked */ + up_read(&cookie->parent->sem); + _leave(" = NULL [parent ubni]"); + return NULL; + } + + up_read(&cookie->parent->sem); + + if (!cookie->parent->def->select_cache) + goto no_preference; + + /* ask the netfs for its preference */ + tag = cookie->parent->def->select_cache( + cookie->parent->parent->netfs_data, + cookie->parent->netfs_data); + + if (!tag) + goto no_preference; + + if (tag == &fscache_nomem_tag) { + _leave(" = NULL [nomem tag]"); + return NULL; + } + + if (!tag->cache) { + _leave(" = NULL [unbacked tag]"); + return NULL; + } + + _leave(" = %p [specific]", tag->cache); + return tag->cache; + +no_preference: + /* netfs has no preference - just select first cache */ + cache = list_entry(fscache_cache_list.next, + struct fscache_cache, link); + _leave(" = %p [first]", cache); + return cache; + +} /* end fscache_select_cache_for_object() */ + +/*****************************************************************************/ +/* + * get a backing object for a cookie from the chosen cache + * - the cookie must be write-locked by the caller + * - all parent indexes will be obtained recursively first + */ +static struct fscache_object *fscache_lookup_object(struct fscache_cookie *cookie, + struct fscache_cache *cache) +{ + struct fscache_cookie *parent = cookie->parent; + struct fscache_object *pobject, *object; + struct hlist_node *_p; + + _enter("{%s/%s},", + parent && parent->def ? parent->def->name : "", + cookie->def ? (char *) cookie->def->name : ""); + + /* see if we have the backing object for this cookie + cache immediately + * to hand + */ + object = NULL; + hlist_for_each_entry(object, _p, + &cookie->backing_objects, cookie_link + ) { + if (object->cache == cache) + break; + } + + if (object) { + _leave(" = %p [old]", object); + return object; + } + + BUG_ON(!parent); /* FSDEF entries don't have a parent */ + + /* we don't have a backing cookie, so we need to consult the object's + * parent index in the selected cache and maybe insert an entry + * therein; so the first thing to do is make sure that the parent index + * is represented on disc + */ + down_read(&parent->sem); + + pobject = NULL; + hlist_for_each_entry(pobject, _p, + &parent->backing_objects, cookie_link + ) { + if (pobject->cache == cache) + break; + } + + if (!pobject) { + /* we don't know about the parent object */ + up_read(&parent->sem); + down_write(&parent->sem); + + pobject = fscache_lookup_object(parent, cache); + if (IS_ERR(pobject)) { + up_write(&parent->sem); + _leave(" = %ld [no ipobj]", PTR_ERR(pobject)); + return pobject; + } + + _debug("pobject=%p", pobject); + + BUG_ON(pobject->cookie != parent); + + downgrade_write(&parent->sem); + } + + /* now we can attempt to look up this object in the parent, possibly + * creating a representation on disc when we do so + */ + object = cache->ops->lookup_object(cache, pobject, cookie); + up_read(&parent->sem); + + if (IS_ERR(object)) { + _leave(" = %ld [no obj]", PTR_ERR(object)); + return object; + } + + /* keep track of it */ + cache->ops->lock_object(object); + + BUG_ON(!hlist_unhashed(&object->cookie_link)); + + /* attach to the cache's object list */ + if (list_empty(&object->cache_link)) { + spin_lock(&cache->object_list_lock); + list_add(&object->cache_link, &cache->object_list); + spin_unlock(&cache->object_list_lock); + } + + /* attach to the cookie */ + object->cookie = cookie; + atomic_inc(&cookie->usage); + hlist_add_head(&object->cookie_link, &cookie->backing_objects); + + /* done */ + cache->ops->unlock_object(object); + _leave(" = %p [new]", object); + return object; + +} /* end fscache_lookup_object() */ + +/*****************************************************************************/ +/* + * request a cookie to represent an object (index, datafile, xattr, etc) + * - parent specifies the parent object + * - the top level index cookie for each netfs is stored in the fscache_netfs + * struct upon registration + * - idef points to the definition + * - the netfs_data will be passed to the functions pointed to in *def + * - all attached caches will be searched to see if they contain this object + * - index objects aren't stored on disk until there's a dependent file that + * needs storing + * - other objects are stored in a selected cache immediately, and all the + * indexes forming the path to it are instantiated if necessary + * - we never let on to the netfs about errors + * - we may set a negative cookie pointer, but that's okay + */ +struct fscache_cookie *__fscache_acquire_cookie(struct fscache_cookie *parent, + struct fscache_cookie_def *def, + void *netfs_data) +{ + struct fscache_cookie *cookie; + struct fscache_cache *cache; + struct fscache_object *object; + int ret = 0; + + BUG_ON(!def); + + _enter("{%s},{%s},%p", + parent ? (char *) parent->def->name : "", + def->name, netfs_data); + + /* if there's no parent cookie, then we don't create one here either */ + if (parent == FSCACHE_NEGATIVE_COOKIE) { + _leave(" [no parent]"); + return FSCACHE_NEGATIVE_COOKIE; + } + + /* validate the definition */ + BUG_ON(!def->get_key); + BUG_ON(!def->name[0]); + + BUG_ON(def->type == FSCACHE_COOKIE_TYPE_INDEX && + parent->def->type != FSCACHE_COOKIE_TYPE_INDEX); + + /* allocate and initialise a cookie */ + cookie = kmem_cache_alloc(fscache_cookie_jar, SLAB_KERNEL); + if (!cookie) { + _leave(" [ENOMEM]"); + return FSCACHE_NEGATIVE_COOKIE; + } + + atomic_set(&cookie->usage, 1); + atomic_set(&cookie->children, 0); + + atomic_inc(&parent->usage); + atomic_inc(&parent->children); + + cookie->def = def; + cookie->parent = parent; + cookie->netfs = parent->netfs; + cookie->netfs_data = netfs_data; + + /* now we need to see whether the backing objects for this cookie yet + * exist, if not there'll be nothing to search */ + down_read(&fscache_addremove_sem); + + if (list_empty(&fscache_cache_list)) { + up_read(&fscache_addremove_sem); + _leave(" = %p [no caches]", cookie); + return cookie; + } + + /* if the object is an index then we need do nothing more here - we + * create indexes on disk when we need them as an index may exist in + * multiple caches */ + if (cookie->def->type != FSCACHE_COOKIE_TYPE_INDEX) { + down_write(&cookie->sem); + + /* the object is a file - we need to select a cache in which to + * store it */ + cache = fscache_select_cache_for_object(cookie); + if (!cache) + goto no_cache; /* couldn't decide on a cache */ + + /* create a file index entry on disc, along with all the + * indexes required to find it again later */ + object = fscache_lookup_object(cookie, cache); + if (IS_ERR(object)) { + ret = PTR_ERR(object); + goto error; + } + + up_write(&cookie->sem); + } +out: + up_read(&fscache_addremove_sem); + _leave(" = %p", cookie); + return cookie; + +no_cache: + ret = -ENOMEDIUM; +error: + printk(KERN_ERR "FS-Cache: error from cache: %d\n", ret); + if (cookie) { + up_write(&cookie->sem); + __fscache_cookie_put(cookie); + cookie = FSCACHE_NEGATIVE_COOKIE; + atomic_dec(&parent->children); + } + + goto out; + +} /* end __fscache_acquire_cookie() */ + +EXPORT_SYMBOL(__fscache_acquire_cookie); + +/*****************************************************************************/ +/* + * release a cookie back to the cache + * - the object will be marked as recyclable on disc if retire is true + * - all dependents of this cookie must have already been unregistered + * (indexes/files/pages) + */ +void __fscache_relinquish_cookie(struct fscache_cookie *cookie, int retire) +{ + struct fscache_cache *cache; + struct fscache_object *object; + struct hlist_node *_p; + + if (cookie == FSCACHE_NEGATIVE_COOKIE) { + _leave(" [no cookie]"); + return; + } + + _enter("%p{%s},%d", cookie, cookie->def->name, retire); + + if (atomic_read(&cookie->children) != 0) { + printk("FS-Cache: cookie still has children\n"); + BUG(); + } + + /* detach pointers back to the netfs */ + down_write(&cookie->sem); + + cookie->netfs_data = NULL; + cookie->def = NULL; + + /* mark retired objects for recycling */ + if (retire) { + hlist_for_each_entry(object, _p, + &cookie->backing_objects, + cookie_link + ) { + set_bit(FSCACHE_OBJECT_RECYCLING, &object->flags); + } + } + + /* break links with all the active objects */ + while (!hlist_empty(&cookie->backing_objects)) { + object = hlist_entry(cookie->backing_objects.first, + struct fscache_object, + cookie_link); + + /* detach each cache object from the object cookie */ + set_bit(FSCACHE_OBJECT_RELEASING, &object->flags); + + hlist_del_init(&object->cookie_link); + + cache = object->cache; + cache->ops->lock_object(object); + object->cookie = NULL; + cache->ops->unlock_object(object); + + if (atomic_dec_and_test(&cookie->usage)) + /* the cookie refcount shouldn't be reduced to 0 yet */ + BUG(); + + spin_lock(&cache->object_list_lock); + list_del_init(&object->cache_link); + spin_unlock(&cache->object_list_lock); + + cache->ops->put_object(object); + } + + up_write(&cookie->sem); + + if (cookie->parent) { +#ifdef CONFIG_DEBUG_SLAB + BUG_ON((atomic_read(&cookie->parent->children) & 0xffff0000) == 0x6b6b0000); +#endif + atomic_dec(&cookie->parent->children); + } + + /* finally dispose of the cookie */ + fscache_cookie_put(cookie); + + _leave(""); + +} /* end __fscache_relinquish_cookie() */ + +EXPORT_SYMBOL(__fscache_relinquish_cookie); + +/*****************************************************************************/ +/* + * update the index entries backing a cookie + */ +void __fscache_update_cookie(struct fscache_cookie *cookie) +{ + struct fscache_object *object; + struct hlist_node *_p; + + if (cookie == FSCACHE_NEGATIVE_COOKIE) { + _leave(" [no cookie]"); + return; + } + + _enter("{%s}", cookie->def->name); + + BUG_ON(!cookie->def->get_aux); + + down_write(&cookie->sem); + down_read(&cookie->parent->sem); + + /* update the index entry on disc in each cache backing this cookie */ + hlist_for_each_entry(object, _p, + &cookie->backing_objects, cookie_link + ) { + object->cache->ops->update_object(object); + } + + up_read(&cookie->parent->sem); + up_write(&cookie->sem); + _leave(""); + +} /* end __fscache_update_cookie() */ + +EXPORT_SYMBOL(__fscache_update_cookie); + +/*****************************************************************************/ +/* + * destroy a cookie + */ +static void __fscache_cookie_put(struct fscache_cookie *cookie) +{ + struct fscache_cookie *parent; + + _enter("%p", cookie); + + for (;;) { + parent = cookie->parent; + BUG_ON(!hlist_empty(&cookie->backing_objects)); + kmem_cache_free(fscache_cookie_jar, cookie); + + if (!parent) + break; + + cookie = parent; + BUG_ON(atomic_read(&cookie->usage) <= 0); + if (!atomic_dec_and_test(&cookie->usage)) + break; + } + + _leave(""); + +} /* end __fscache_cookie_put() */ + +/*****************************************************************************/ +/* + * initialise an cookie jar slab element prior to any use + */ +void fscache_cookie_init_once(void *_cookie, kmem_cache_t *cachep, + unsigned long flags) +{ + struct fscache_cookie *cookie = _cookie; + + if ((flags & (SLAB_CTOR_VERIFY|SLAB_CTOR_CONSTRUCTOR)) == + SLAB_CTOR_CONSTRUCTOR) { + memset(cookie, 0, sizeof(*cookie)); + init_rwsem(&cookie->sem); + INIT_HLIST_HEAD(&cookie->backing_objects); + } + +} /* end fscache_cookie_init_once() */ + +/*****************************************************************************/ +/* + * pin an object into the cache + */ +int __fscache_pin_cookie(struct fscache_cookie *cookie) +{ + struct fscache_object *object; + int ret; + + _enter("%p", cookie); + + if (hlist_empty(&cookie->backing_objects)) { + _leave(" = -ENOBUFS"); + return -ENOBUFS; + } + + /* not supposed to use this for indexes */ + BUG_ON(cookie->def->type == FSCACHE_COOKIE_TYPE_INDEX); + + /* prevent the file from being uncached whilst we access it and exclude + * read and write attempts on pages + */ + down_write(&cookie->sem); + + ret = -ENOBUFS; + if (!hlist_empty(&cookie->backing_objects)) { + /* get and pin the backing object */ + object = hlist_entry(cookie->backing_objects.first, + struct fscache_object, cookie_link); + + if (!object->cache->ops->pin_object) { + ret = -EOPNOTSUPP; + goto out; + } + + /* prevent the cache from being withdrawn */ + if (down_read_trylock(&object->cache->withdrawal_sem)) { + if (object->cache->ops->grab_object(object)) { + /* ask the cache to honour the operation */ + ret = object->cache->ops->pin_object(object); + + object->cache->ops->put_object(object); + } + + up_read(&object->cache->withdrawal_sem); + } + } + +out: + up_write(&cookie->sem); + _leave(" = %d", ret); + return ret; + +} /* end __fscache_pin_cookie() */ + +EXPORT_SYMBOL(__fscache_pin_cookie); + +/*****************************************************************************/ +/* + * unpin an object into the cache + */ +void __fscache_unpin_cookie(struct fscache_cookie *cookie) +{ + struct fscache_object *object; + int ret; + + _enter("%p", cookie); + + if (hlist_empty(&cookie->backing_objects)) { + _leave(" [no obj]"); + return; + } + + /* not supposed to use this for indexes */ + BUG_ON(cookie->def->type == FSCACHE_COOKIE_TYPE_INDEX); + + /* prevent the file from being uncached whilst we access it and exclude + * read and write attempts on pages + */ + down_write(&cookie->sem); + + ret = -ENOBUFS; + if (!hlist_empty(&cookie->backing_objects)) { + /* get and unpin the backing object */ + object = hlist_entry(cookie->backing_objects.first, + struct fscache_object, cookie_link); + + if (!object->cache->ops->unpin_object) + goto out; + + /* prevent the cache from being withdrawn */ + if (down_read_trylock(&object->cache->withdrawal_sem)) { + if (object->cache->ops->grab_object(object)) { + /* ask the cache to honour the operation */ + object->cache->ops->unpin_object(object); + + object->cache->ops->put_object(object); + } + + up_read(&object->cache->withdrawal_sem); + } + } + +out: + up_write(&cookie->sem); + _leave(""); + +} /* end __fscache_unpin_cookie() */ + +EXPORT_SYMBOL(__fscache_unpin_cookie); --- /dev/null 2006-03-18 10:17:16.106812576 -0500 +++ linux-2.6.16.noarch/fs/fscache/fscache-int.h 2006-03-27 09:49:31.000000000 -0500 @@ -0,0 +1,71 @@ +/* fscache-int.h: internal definitions + * + * Copyright (C) 2004 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. + */ + +#ifndef _FSCACHE_INT_H +#define _FSCACHE_INT_H + +#include +#include +#include + +extern kmem_cache_t *fscache_cookie_jar; + +extern struct fscache_cookie fscache_fsdef_index; +extern struct fscache_cookie_def fscache_fsdef_netfs_def; + +extern void fscache_cookie_init_once(void *_cookie, kmem_cache_t *cachep, unsigned long flags); + +/*****************************************************************************/ +/* + * debug tracing + */ +#define dbgprintk(FMT,...) \ + printk("[%-6.6s] "FMT"\n",current->comm ,##__VA_ARGS__) +#define _dbprintk(FMT,...) do { } while(0) + +#define kenter(FMT,...) dbgprintk("==> %s("FMT")",__FUNCTION__ ,##__VA_ARGS__) +#define kleave(FMT,...) dbgprintk("<== %s()"FMT"",__FUNCTION__ ,##__VA_ARGS__) +#define kdebug(FMT,...) dbgprintk(FMT ,##__VA_ARGS__) + +#define kjournal(FMT,...) _dbprintk(FMT ,##__VA_ARGS__) + +#define dbgfree(ADDR) _dbprintk("%p:%d: FREEING %p",__FILE__,__LINE__,ADDR) + +#define dbgpgalloc(PAGE) \ +do { \ + _dbprintk("PGALLOC %s:%d: %p {%lx,%lu}\n", \ + __FILE__,__LINE__, \ + (PAGE),(PAGE)->mapping->host->i_ino,(PAGE)->index \ + ); \ +} while(0) + +#define dbgpgfree(PAGE) \ +do { \ + if ((PAGE)) \ + _dbprintk("PGFREE %s:%d: %p {%lx,%lu}\n", \ + __FILE__,__LINE__, \ + (PAGE), \ + (PAGE)->mapping->host->i_ino, \ + (PAGE)->index \ + ); \ +} while(0) + +#ifdef __KDEBUG +#define _enter(FMT,...) kenter(FMT,##__VA_ARGS__) +#define _leave(FMT,...) kleave(FMT,##__VA_ARGS__) +#define _debug(FMT,...) kdebug(FMT,##__VA_ARGS__) +#else +#define _enter(FMT,...) do { } while(0) +#define _leave(FMT,...) do { } while(0) +#define _debug(FMT,...) do { } while(0) +#endif + +#endif /* _FSCACHE_INT_H */ --- /dev/null 2006-03-18 10:17:16.106812576 -0500 +++ linux-2.6.16.noarch/fs/fscache/fsdef.c 2006-03-27 09:49:31.000000000 -0500 @@ -0,0 +1,113 @@ +/* fsdef.c: filesystem index definition + * + * Copyright (C) 2004 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. + */ + +#include +#include "fscache-int.h" + +static uint16_t fscache_fsdef_netfs_get_key(const void *cookie_netfs_data, + void *buffer, uint16_t bufmax); + +static uint16_t fscache_fsdef_netfs_get_aux(const void *cookie_netfs_data, + void *buffer, uint16_t bufmax); + +static fscache_checkaux_t fscache_fsdef_netfs_check_aux(void *cookie_netfs_data, + const void *data, + uint16_t datalen); + +struct fscache_cookie_def fscache_fsdef_netfs_def = { + .name = "FSDEF.netfs", + .type = FSCACHE_COOKIE_TYPE_INDEX, + .get_key = fscache_fsdef_netfs_get_key, + .get_aux = fscache_fsdef_netfs_get_aux, + .check_aux = fscache_fsdef_netfs_check_aux, +}; + +struct fscache_cookie fscache_fsdef_index = { + .usage = ATOMIC_INIT(1), + .def = NULL, + .sem = __RWSEM_INITIALIZER(fscache_fsdef_index.sem), + .backing_objects = HLIST_HEAD_INIT, +}; + +EXPORT_SYMBOL(fscache_fsdef_index); + +/*****************************************************************************/ +/* + * get the key data for an FSDEF index record + */ +static uint16_t fscache_fsdef_netfs_get_key(const void *cookie_netfs_data, + void *buffer, uint16_t bufmax) +{ + const struct fscache_netfs *netfs = cookie_netfs_data; + unsigned klen; + + _enter("{%s.%u},", netfs->name, netfs->version); + + klen = strlen(netfs->name); + if (klen > bufmax) + return 0; + + memcpy(buffer, netfs->name, klen); + return klen; + +} /* end fscache_fsdef_netfs_get_key() */ + +/*****************************************************************************/ +/* + * get the auxilliary data for an FSDEF index record + */ +static uint16_t fscache_fsdef_netfs_get_aux(const void *cookie_netfs_data, + void *buffer, uint16_t bufmax) +{ + const struct fscache_netfs *netfs = cookie_netfs_data; + unsigned dlen; + + _enter("{%s.%u},", netfs->name, netfs->version); + + dlen = sizeof(uint32_t); + if (dlen > bufmax) + return 0; + + memcpy(buffer, &netfs->version, dlen); + return dlen; + +} /* end fscache_fsdef_netfs_get_aux() */ + +/*****************************************************************************/ +/* + * check that the version stored in the auxilliary data is correct + */ +static fscache_checkaux_t fscache_fsdef_netfs_check_aux(void *cookie_netfs_data, + const void *data, + uint16_t datalen) +{ + struct fscache_netfs *netfs = cookie_netfs_data; + uint32_t version; + + _enter("{%s},,%hu", netfs->name, datalen); + + if (datalen != sizeof(version)) { + _leave(" = OBSOLETE [dl=%d v=%d]", + datalen, sizeof(version)); + return FSCACHE_CHECKAUX_OBSOLETE; + } + + memcpy(&version, data, sizeof(version)); + if (version != netfs->version) { + _leave(" = OBSOLETE [ver=%x net=%x]", + version, netfs->version); + return FSCACHE_CHECKAUX_OBSOLETE; + } + + _leave(" = OKAY"); + return FSCACHE_CHECKAUX_OKAY; + +} /* end fscache_fsdef_netfs_check_aux() */ --- /dev/null 2006-03-18 10:17:16.106812576 -0500 +++ linux-2.6.16.noarch/fs/fscache/main.c 2006-03-27 09:49:31.000000000 -0500 @@ -0,0 +1,112 @@ +/* main.c: general filesystem caching manager + * + * Copyright (C) 2004 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. + */ + +#include +#include +#include +#include +#include +#include "fscache-int.h" + +int fscache_debug = 0; + +static int fscache_init(void); +static void fscache_exit(void); + +fs_initcall(fscache_init); +module_exit(fscache_exit); + +MODULE_DESCRIPTION("FS Cache Manager"); +MODULE_AUTHOR("Red Hat, Inc."); +MODULE_LICENSE("GPL"); + +/*****************************************************************************/ +/* + * initialise the fs caching module + */ +static int fscache_init(void) +{ + fscache_cookie_jar = + kmem_cache_create("fscache_cookie_jar", + sizeof(struct fscache_cookie), + 0, + 0, + fscache_cookie_init_once, + NULL); + + if (!fscache_cookie_jar) { + printk(KERN_NOTICE + "FS-Cache: Failed to allocate a cookie jar\n"); + return -ENOMEM; + } + + printk(KERN_NOTICE "FS-Cache: Loaded\n"); + return 0; + +} /* end fscache_init() */ + +/*****************************************************************************/ +/* + * clean up on module removal + */ +static void __exit fscache_exit(void) +{ + _enter(""); + + kmem_cache_destroy(fscache_cookie_jar); + printk(KERN_NOTICE "FS-Cache: unloaded\n"); + +} /* end fscache_exit() */ + +/*****************************************************************************/ +/* + * clear the dead space between task_struct and kernel stack + * - called by supplying -finstrument-functions to gcc + */ +#if 0 +void __cyg_profile_func_enter (void *this_fn, void *call_site) +__attribute__((no_instrument_function)); + +void __cyg_profile_func_enter (void *this_fn, void *call_site) +{ + asm volatile(" movl %%esp,%%edi \n" + " andl %0,%%edi \n" + " addl %1,%%edi \n" + " movl %%esp,%%ecx \n" + " subl %%edi,%%ecx \n" + " shrl $2,%%ecx \n" + " movl $0xedededed,%%eax \n" + " rep stosl \n" + : + : "i"(~(THREAD_SIZE-1)), "i"(sizeof(struct thread_info)) + : "eax", "ecx", "edi", "memory", "cc" + ); +} + +void __cyg_profile_func_exit(void *this_fn, void *call_site) +__attribute__((no_instrument_function)); + +void __cyg_profile_func_exit(void *this_fn, void *call_site) +{ + asm volatile(" movl %%esp,%%edi \n" + " andl %0,%%edi \n" + " addl %1,%%edi \n" + " movl %%esp,%%ecx \n" + " subl %%edi,%%ecx \n" + " shrl $2,%%ecx \n" + " movl $0xdadadada,%%eax \n" + " rep stosl \n" + : + : "i"(~(THREAD_SIZE-1)), "i"(sizeof(struct thread_info)) + : "eax", "ecx", "edi", "memory", "cc" + ); +} +#endif --- /dev/null 2006-03-18 10:17:16.106812576 -0500 +++ linux-2.6.16.noarch/fs/fscache/page.c 2006-03-27 09:49:31.000000000 -0500 @@ -0,0 +1,521 @@ +/* page.c: general filesystem cache cookie management + * + * Copyright (C) 2004-5 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. + */ + +#include +#include +#include +#include +#include "fscache-int.h" + +/*****************************************************************************/ +/* + * set the data file size on an object in the cache + */ +int __fscache_set_i_size(struct fscache_cookie *cookie, loff_t i_size) +{ + struct fscache_object *object; + int ret; + + _enter("%p,%llu,", cookie, i_size); + + if (hlist_empty(&cookie->backing_objects)) { + _leave(" = -ENOBUFS"); + return -ENOBUFS; + } + + /* not supposed to use this for indexes */ + BUG_ON(cookie->def->type == FSCACHE_COOKIE_TYPE_INDEX); + + /* prevent the file from being uncached whilst we access it and exclude + * read and write attempts on pages + */ + down_write(&cookie->sem); + + ret = -ENOBUFS; + if (!hlist_empty(&cookie->backing_objects)) { + /* get and pin the backing object */ + object = hlist_entry(cookie->backing_objects.first, + struct fscache_object, cookie_link); + + /* prevent the cache from being withdrawn */ + if (object->cache->ops->set_i_size && + down_read_trylock(&object->cache->withdrawal_sem) + ) { + if (object->cache->ops->grab_object(object)) { + /* ask the cache to honour the operation */ + ret = object->cache->ops->set_i_size(object, + i_size); + + object->cache->ops->put_object(object); + } + + up_read(&object->cache->withdrawal_sem); + } + } + + up_write(&cookie->sem); + _leave(" = %d", ret); + return ret; + +} /* end __fscache_set_i_size() */ + +EXPORT_SYMBOL(__fscache_set_i_size); + +/*****************************************************************************/ +/* + * reserve space for an object + */ +int __fscache_reserve_space(struct fscache_cookie *cookie, loff_t size) +{ + struct fscache_object *object; + int ret; + + _enter("%p,%llu,", cookie, size); + + if (hlist_empty(&cookie->backing_objects)) { + _leave(" = -ENOBUFS"); + return -ENOBUFS; + } + + /* not supposed to use this for indexes */ + BUG_ON(cookie->def->type == FSCACHE_COOKIE_TYPE_INDEX); + + /* prevent the file from being uncached whilst we access it and exclude + * read and write attempts on pages + */ + down_write(&cookie->sem); + + ret = -ENOBUFS; + if (!hlist_empty(&cookie->backing_objects)) { + /* get and pin the backing object */ + object = hlist_entry(cookie->backing_objects.first, + struct fscache_object, cookie_link); + + if (!object->cache->ops->reserve_space) { + ret = -EOPNOTSUPP; + goto out; + } + + /* prevent the cache from being withdrawn */ + if (down_read_trylock(&object->cache->withdrawal_sem)) { + if (object->cache->ops->grab_object(object)) { + /* ask the cache to honour the operation */ + ret = object->cache->ops->reserve_space(object, + size); + + object->cache->ops->put_object(object); + } + + up_read(&object->cache->withdrawal_sem); + } + } + +out: + up_write(&cookie->sem); + _leave(" = %d", ret); + return ret; + +} /* end __fscache_reserve_space() */ + +EXPORT_SYMBOL(__fscache_reserve_space); + +/*****************************************************************************/ +/* + * read a page from the cache or allocate a block in which to store it + * - we return: + * -ENOMEM - out of memory, nothing done + * -EINTR - interrupted + * -ENOBUFS - no backing object available in which to cache the block + * -ENODATA - no data available in the backing object for this block + * 0 - dispatched a read - it'll call end_io_func() when finished + */ +int __fscache_read_or_alloc_page(struct fscache_cookie *cookie, + struct page *page, + fscache_rw_complete_t end_io_func, + void *end_io_data, + gfp_t gfp) +{ + struct fscache_object *object; + int ret; + + _enter("%p,{%lu},", cookie, page->index); + + if (hlist_empty(&cookie->backing_objects)) { + _leave(" -ENOBUFS [no backing objects]"); + return -ENOBUFS; + } + + /* not supposed to use this for indexes */ + BUG_ON(cookie->def->type == FSCACHE_COOKIE_TYPE_INDEX); + + /* prevent the file from being uncached whilst we access it */ + down_read(&cookie->sem); + + ret = -ENOBUFS; + if (!hlist_empty(&cookie->backing_objects)) { + /* get and pin the backing object */ + object = hlist_entry(cookie->backing_objects.first, + struct fscache_object, cookie_link); + + /* prevent the cache from being withdrawn */ + if (down_read_trylock(&object->cache->withdrawal_sem)) { + if (object->cache->ops->grab_object(object)) { + /* ask the cache to honour the operation */ + ret = object->cache->ops->read_or_alloc_page( + object, + page, + end_io_func, + end_io_data, + gfp); + + object->cache->ops->put_object(object); + } + + up_read(&object->cache->withdrawal_sem); + } + } + + up_read(&cookie->sem); + _leave(" = %d", ret); + return ret; + +} /* end __fscache_read_or_alloc_page() */ + +EXPORT_SYMBOL(__fscache_read_or_alloc_page); + +/*****************************************************************************/ +/* + * read a list of page from the cache or allocate a block in which to store + * them + * - we return: + * -ENOMEM - out of memory, some pages may be being read + * -EINTR - interrupted, some pages may be being read + * -ENOBUFS - no backing object or space available in which to cache any + * pages not being read + * -ENODATA - no data available in the backing object for some or all of + * the pages + * 0 - dispatched a read on all pages + * + * end_io_func() will be called for each page read from the cache as it is + * finishes being read + * + * any pages for which a read is dispatched will be removed from pages and + * nr_pages + */ +int __fscache_read_or_alloc_pages(struct fscache_cookie *cookie, + struct address_space *mapping, + struct list_head *pages, + unsigned *nr_pages, + fscache_rw_complete_t end_io_func, + void *end_io_data, + gfp_t gfp) +{ + struct fscache_object *object; + int ret; + + _enter("%p,,%d,,,", cookie, *nr_pages); + + if (hlist_empty(&cookie->backing_objects)) { + _leave(" -ENOBUFS [no backing objects]"); + return -ENOBUFS; + } + + /* not supposed to use this for indexes */ + BUG_ON(cookie->def->type == FSCACHE_COOKIE_TYPE_INDEX); + BUG_ON(list_empty(pages)); + BUG_ON(*nr_pages <= 0); + + /* prevent the file from being uncached whilst we access it */ + down_read(&cookie->sem); + + ret = -ENOBUFS; + if (!hlist_empty(&cookie->backing_objects)) { + /* get and pin the backing object */ + object = hlist_entry(cookie->backing_objects.first, + struct fscache_object, cookie_link); + + /* prevent the cache from being withdrawn */ + if (down_read_trylock(&object->cache->withdrawal_sem)) { + if (object->cache->ops->grab_object(object)) { + /* ask the cache to honour the operation */ + ret = object->cache->ops->read_or_alloc_pages( + object, + mapping, + pages, + nr_pages, + end_io_func, + end_io_data, + gfp); + + object->cache->ops->put_object(object); + } + + up_read(&object->cache->withdrawal_sem); + } + } + + up_read(&cookie->sem); + _leave(" = %d", ret); + return ret; + +} /* end __fscache_read_or_alloc_pages() */ + +EXPORT_SYMBOL(__fscache_read_or_alloc_pages); + +/*****************************************************************************/ +/* + * allocate a block in the cache on which to store a page + * - we return: + * -ENOMEM - out of memory, nothing done + * -EINTR - interrupted + * -ENOBUFS - no backing object available in which to cache the block + * 0 - block allocated + */ +int __fscache_alloc_page(struct fscache_cookie *cookie, + struct page *page, + gfp_t gfp) +{ + struct fscache_object *object; + int ret; + + _enter("%p,{%lu},", cookie, page->index); + + if (hlist_empty(&cookie->backing_objects)) { + _leave(" -ENOBUFS [no backing objects]"); + return -ENOBUFS; + } + + /* not supposed to use this for indexes */ + BUG_ON(cookie->def->type == FSCACHE_COOKIE_TYPE_INDEX); + + /* prevent the file from being uncached whilst we access it */ + down_read(&cookie->sem); + + ret = -ENOBUFS; + if (!hlist_empty(&cookie->backing_objects)) { + /* get and pin the backing object */ + object = hlist_entry(cookie->backing_objects.first, + struct fscache_object, cookie_link); + + /* prevent the cache from being withdrawn */ + if (down_read_trylock(&object->cache->withdrawal_sem)) { + if (object->cache->ops->grab_object(object)) { + /* ask the cache to honour the operation */ + ret = object->cache->ops->allocate_page(object, + page, + gfp); + + object->cache->ops->put_object(object); + } + + up_read(&object->cache->withdrawal_sem); + } + } + + up_read(&cookie->sem); + _leave(" = %d", ret); + return ret; + +} /* end __fscache_alloc_page() */ + +EXPORT_SYMBOL(__fscache_alloc_page); + +/*****************************************************************************/ +/* + * request a page be stored in the cache + * - returns: + * -ENOMEM - out of memory, nothing done + * -EINTR - interrupted + * -ENOBUFS - no backing object available in which to cache the page + * 0 - dispatched a write - it'll call end_io_func() when finished + */ +int __fscache_write_page(struct fscache_cookie *cookie, + struct page *page, + fscache_rw_complete_t end_io_func, + void *end_io_data, + gfp_t gfp) +{ + struct fscache_object *object; + int ret; + + _enter("%p,{%lu},", cookie, page->index); + + /* not supposed to use this for indexes */ + BUG_ON(cookie->def->type == FSCACHE_COOKIE_TYPE_INDEX); + + /* prevent the file from been uncached whilst we deal with it */ + down_read(&cookie->sem); + + ret = -ENOBUFS; + if (!hlist_empty(&cookie->backing_objects)) { + object = hlist_entry(cookie->backing_objects.first, + struct fscache_object, cookie_link); + + /* prevent the cache from being withdrawn */ + if (down_read_trylock(&object->cache->withdrawal_sem)) { + /* ask the cache to honour the operation */ + ret = object->cache->ops->write_page(object, + page, + end_io_func, + end_io_data, + gfp); + up_read(&object->cache->withdrawal_sem); + } + } + + up_read(&cookie->sem); + _leave(" = %d", ret); + return ret; + +} /* end __fscache_write_page() */ + +EXPORT_SYMBOL(__fscache_write_page); + +/*****************************************************************************/ +/* + * request several pages be stored in the cache + * - returns: + * -ENOMEM - out of memory, nothing done + * -EINTR - interrupted + * -ENOBUFS - no backing object available in which to cache the page + * 0 - dispatched a write - it'll call end_io_func() when finished + */ +int __fscache_write_pages(struct fscache_cookie *cookie, + struct pagevec *pagevec, + fscache_rw_complete_t end_io_func, + void *end_io_data, + gfp_t gfp) +{ + struct fscache_object *object; + int ret; + + _enter("%p,{%ld},", cookie, pagevec->nr); + + /* not supposed to use this for indexes */ + BUG_ON(cookie->def->type == FSCACHE_COOKIE_TYPE_INDEX); + + /* prevent the file from been uncached whilst we deal with it */ + down_read(&cookie->sem); + + ret = -ENOBUFS; + if (!hlist_empty(&cookie->backing_objects)) { + object = hlist_entry(cookie->backing_objects.first, + struct fscache_object, cookie_link); + + /* prevent the cache from being withdrawn */ + if (down_read_trylock(&object->cache->withdrawal_sem)) { + /* ask the cache to honour the operation */ + ret = object->cache->ops->write_pages(object, + pagevec, + end_io_func, + end_io_data, + gfp); + up_read(&object->cache->withdrawal_sem); + } + } + + up_read(&cookie->sem); + _leave(" = %d", ret); + return ret; + +} /* end __fscache_write_pages() */ + +EXPORT_SYMBOL(__fscache_write_pages); + +/*****************************************************************************/ +/* + * remove a page from the cache + */ +void __fscache_uncache_page(struct fscache_cookie *cookie, struct page *page) +{ + struct fscache_object *object; + struct pagevec pagevec; + + _enter(",{%lu}", page->index); + + /* not supposed to use this for indexes */ + BUG_ON(cookie->def->type == FSCACHE_COOKIE_TYPE_INDEX); + + if (hlist_empty(&cookie->backing_objects)) { + _leave(" [no backing]"); + return; + } + + pagevec_init(&pagevec, 0); + pagevec_add(&pagevec, page); + + /* ask the cache to honour the operation */ + down_read(&cookie->sem); + + if (!hlist_empty(&cookie->backing_objects)) { + object = hlist_entry(cookie->backing_objects.first, + struct fscache_object, cookie_link); + + /* prevent the cache from being withdrawn */ + if (down_read_trylock(&object->cache->withdrawal_sem)) { + object->cache->ops->uncache_pages(object, &pagevec); + up_read(&object->cache->withdrawal_sem); + } + } + + up_read(&cookie->sem); + + _leave(""); + return; + +} /* end __fscache_uncache_page() */ + +EXPORT_SYMBOL(__fscache_uncache_page); + +/*****************************************************************************/ +/* + * remove a bunch of pages from the cache + */ +void __fscache_uncache_pages(struct fscache_cookie *cookie, + struct pagevec *pagevec) +{ + struct fscache_object *object; + + _enter(",{%ld}", pagevec->nr); + + BUG_ON(pagevec->nr <= 0); + BUG_ON(!pagevec->pages[0]); + + /* not supposed to use this for indexes */ + BUG_ON(cookie->def->type == FSCACHE_COOKIE_TYPE_INDEX); + + if (hlist_empty(&cookie->backing_objects)) { + _leave(" [no backing]"); + return; + } + + /* ask the cache to honour the operation */ + down_read(&cookie->sem); + + if (!hlist_empty(&cookie->backing_objects)) { + object = hlist_entry(cookie->backing_objects.first, + struct fscache_object, cookie_link); + + /* prevent the cache from being withdrawn */ + if (down_read_trylock(&object->cache->withdrawal_sem)) { + object->cache->ops->uncache_pages(object, pagevec); + up_read(&object->cache->withdrawal_sem); + } + } + + up_read(&cookie->sem); + + _leave(""); + return; + +} /* end __fscache_uncache_pages() */ + +EXPORT_SYMBOL(__fscache_uncache_pages); --- /dev/null 2006-03-18 10:17:16.106812576 -0500 +++ linux-2.6.16.noarch/include/linux/fscache-cache.h 2006-03-27 09:49:31.000000000 -0500 @@ -0,0 +1,216 @@ +/* fscache-cache.h: general filesystem caching backing cache interface + * + * Copyright (C) 2004-5 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. + */ + +#ifndef _LINUX_FSCACHE_CACHE_H +#define _LINUX_FSCACHE_CACHE_H + +#include + +#define NR_MAXCACHES BITS_PER_LONG + +struct fscache_cache; +struct fscache_cache_ops; +struct fscache_object; + +/* + * cache tag definition + */ +struct fscache_cache_tag { + struct list_head link; + struct fscache_cache *cache; /* cache referred to by this tag */ + atomic_t usage; + char name[0]; /* tag name */ +}; + +/* + * cache definition + */ +struct fscache_cache { + struct fscache_cache_ops *ops; + struct fscache_cache_tag *tag; /* tag representing this cache */ + struct list_head link; /* link in list of caches */ + struct rw_semaphore withdrawal_sem; /* withdrawal control sem */ + size_t max_index_size; /* maximum size of index data */ + char identifier[32]; /* cache label */ + + /* node management */ + struct list_head object_list; /* list of data/index objects */ + spinlock_t object_list_lock; + struct fscache_object *fsdef; /* object for the fsdef index */ +}; + +extern void fscache_init_cache(struct fscache_cache *cache, + struct fscache_cache_ops *ops, + const char *idfmt, + ...) __attribute__ ((format (printf,3,4))); + +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); + +/*****************************************************************************/ +/* + * cache operations + */ +struct fscache_cache_ops { + /* name of cache provider */ + const char *name; + + /* look up the object for a cookie, creating it on disc if necessary */ + struct fscache_object *(*lookup_object)(struct fscache_cache *cache, + struct fscache_object *parent, + struct fscache_cookie *cookie); + + /* increment the usage count on this object (may fail if unmounting) */ + struct fscache_object *(*grab_object)(struct fscache_object *object); + + /* lock a semaphore on an object */ + void (*lock_object)(struct fscache_object *object); + + /* unlock a semaphore on an object */ + void (*unlock_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 auxilliary data on an object */ + void (*update_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); + + /* set the data size of an object */ + int (*set_i_size)(struct fscache_object *object, loff_t i_size); + + /* 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 */ + int (*read_or_alloc_page)(struct fscache_object *object, + struct page *page, + fscache_rw_complete_t end_io_func, + void *end_io_data, + unsigned long gfp); + + /* request backing blocks for a list of pages be read or allocated in + * the cache */ + int (*read_or_alloc_pages)(struct fscache_object *object, + struct address_space *mapping, + struct list_head *pages, + unsigned *nr_pages, + fscache_rw_complete_t end_io_func, + void *end_io_data, + unsigned long gfp); + + /* request a backing block for a page be allocated in the cache so that + * it can be written directly */ + int (*allocate_page)(struct fscache_object *object, + struct page *page, + unsigned long gfp); + + /* write a page to its backing block in the cache */ + int (*write_page)(struct fscache_object *object, + struct page *page, + fscache_rw_complete_t end_io_func, + void *end_io_data, + unsigned long gfp); + + /* write several pages to their backing blocks in the cache */ + int (*write_pages)(struct fscache_object *object, + struct pagevec *pagevec, + fscache_rw_complete_t end_io_func, + void *end_io_data, + unsigned long gfp); + + /* detach backing block from a bunch of pages */ + void (*uncache_pages)(struct fscache_object *object, + struct pagevec *pagevec); + + /* 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 disc space + * - indexes files are created on disc just-in-time + */ +struct fscache_cookie { + atomic_t usage; /* number of users of this cookie */ + atomic_t children; /* number of children of this cookie */ + struct rw_semaphore sem; /* list creation vs scan lock */ + struct hlist_head backing_objects; /* object(s) backing this file/index */ + struct fscache_cookie_def *def; /* definition */ + struct fscache_cookie *parent; /* parent of this entry */ + struct fscache_netfs *netfs; /* owner network fs definition */ + void *netfs_data; /* back pointer to netfs */ +}; + +extern struct fscache_cookie fscache_fsdef_index; + +/*****************************************************************************/ +/* + * on-disc cache file or index handle + */ +struct fscache_object { + unsigned long flags; +#define FSCACHE_OBJECT_RELEASING 0 /* T if object is being released */ +#define FSCACHE_OBJECT_RECYCLING 1 /* T if object is being retired */ +#define FSCACHE_OBJECT_WITHDRAWN 2 /* T if object has been withdrawn */ + + 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 */ +}; + +static inline +void fscache_object_init(struct fscache_object *object) +{ + object->flags = 0; + INIT_LIST_HEAD(&object->cache_link); + INIT_HLIST_NODE(&object->cookie_link); + object->cache = NULL; + object->cookie = NULL; +} + +/* find the parent index object for a object */ +static inline +struct fscache_object *fscache_find_parent_object(struct fscache_object *object) +{ + struct fscache_object *parent; + struct fscache_cookie *cookie = object->cookie; + struct fscache_cache *cache = object->cache; + struct hlist_node *_p; + + hlist_for_each_entry(parent, _p, + &cookie->parent->backing_objects, + cookie_link + ) { + if (parent->cache == cache) + return parent; + } + + return NULL; +} + +#endif /* _LINUX_FSCACHE_CACHE_H */ --- /dev/null 2006-03-18 10:17:16.106812576 -0500 +++ linux-2.6.16.noarch/include/linux/fscache.h 2006-03-27 09:49:31.000000000 -0500 @@ -0,0 +1,484 @@ +/* fscache.h: general filesystem caching interface + * + * Copyright (C) 2004-5 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. + */ + +#ifndef _LINUX_FSCACHE_H +#define _LINUX_FSCACHE_H + +#include +#include +#include +#include +#include + +#ifdef CONFIG_FSCACHE_MODULE +#define CONFIG_FSCACHE +#endif + +struct pagevec; +struct fscache_cache_tag; +struct fscache_cookie; +struct fscache_netfs; +struct fscache_netfs_operations; + +#define FSCACHE_NEGATIVE_COOKIE ((struct fscache_cookie *) NULL) + +typedef void (*fscache_rw_complete_t)(struct page *page, + void *data, + int error); + +/* result of index entry consultation */ +typedef enum { + FSCACHE_CHECKAUX_OKAY, /* entry okay as is */ + FSCACHE_CHECKAUX_NEEDS_UPDATE, /* entry requires update */ + FSCACHE_CHECKAUX_OBSOLETE, /* entry requires deletion */ +} fscache_checkaux_t; + +/*****************************************************************************/ +/* + * fscache cookie definition + */ +struct fscache_cookie_def +{ + /* name of cookie type */ + char name[16]; + + /* cookie type */ + uint8_t type; +#define FSCACHE_COOKIE_TYPE_INDEX 0 +#define FSCACHE_COOKIE_TYPE_DATAFILE 1 + + /* select the cache into which to insert an entry in this index + * - optional + * - should return a cache identifier or NULL to cause the cache to be + * inherited from the parent if possible or the first cache picked + * for a non-index file if not + */ + struct fscache_cache_tag *(*select_cache)(const void *parent_netfs_data, + const void *cookie_netfs_data); + + /* get an index key + * - should store the key data in the buffer + * - should return the amount of amount stored + * - not permitted to return an error + * - the netfs data from the cookie being used as the source is + * presented + */ + uint16_t (*get_key)(const void *cookie_netfs_data, + void *buffer, + uint16_t bufmax); + + /* get certain file attributes from the netfs data + * - this function can be absent for an index + * - not permitted to return an error + * - the netfs data from the cookie being used as the source is + * presented + */ + void (*get_attr)(const void *cookie_netfs_data, uint64_t *size); + + /* get the auxilliary data from netfs data + * - this function can be absent if the index carries no state data + * - should store the auxilliary data in the buffer + * - should return the amount of amount stored + * - not permitted to return an error + * - the netfs data from the cookie being used as the source is + * presented + */ + uint16_t (*get_aux)(const void *cookie_netfs_data, + void *buffer, + uint16_t bufmax); + + /* consult the netfs about the state of an object + * - this function can be absent if the index carries no state data + * - the netfs data from the cookie being used as the target is + * presented, as is the auxilliary data + */ + fscache_checkaux_t (*check_aux)(void *cookie_netfs_data, + const void *data, + uint16_t datalen); + + /* indicate pages that now have cache metadata retained + * - this function should mark the specified pages as now being cached + */ + void (*mark_pages_cached)(void *cookie_netfs_data, + struct address_space *mapping, + struct pagevec *cached_pvec); + + /* indicate the cookie is no longer uncached + * - this function is called when the backing store currently caching + * a cookie is removed + * - the netfs should use this to clean up any markers indicating + * cached pages + * - this is mandatory for any object that may have data + */ + void (*now_uncached)(void *cookie_netfs_data); +}; + +/* pattern used to fill dead space in an index entry */ +#define FSCACHE_INDEX_DEADFILL_PATTERN 0x79 + +#ifdef CONFIG_FSCACHE +extern struct fscache_cookie *__fscache_acquire_cookie(struct fscache_cookie *parent, + struct fscache_cookie_def *def, + void *netfs_data); + +extern void __fscache_relinquish_cookie(struct fscache_cookie *cookie, + int retire); + +extern void __fscache_update_cookie(struct fscache_cookie *cookie); +#endif + +static inline +struct fscache_cookie *fscache_acquire_cookie(struct fscache_cookie *parent, + struct fscache_cookie_def *def, + void *netfs_data) +{ +#ifdef CONFIG_FSCACHE + if (parent != FSCACHE_NEGATIVE_COOKIE) + return __fscache_acquire_cookie(parent, def, netfs_data); +#endif + return FSCACHE_NEGATIVE_COOKIE; +} + +static inline +void fscache_relinquish_cookie(struct fscache_cookie *cookie, + int retire) +{ +#ifdef CONFIG_FSCACHE + if (cookie != FSCACHE_NEGATIVE_COOKIE) + __fscache_relinquish_cookie(cookie, retire); +#endif +} + +static inline +void fscache_update_cookie(struct fscache_cookie *cookie) +{ +#ifdef CONFIG_FSCACHE + if (cookie != FSCACHE_NEGATIVE_COOKIE) + __fscache_update_cookie(cookie); +#endif +} + +/*****************************************************************************/ +/* + * pin or unpin a cookie in a cache + * - only available for data cookies + */ +#ifdef CONFIG_FSCACHE +extern int __fscache_pin_cookie(struct fscache_cookie *cookie); +extern void __fscache_unpin_cookie(struct fscache_cookie *cookie); +#endif + +static inline +int fscache_pin_cookie(struct fscache_cookie *cookie) +{ +#ifdef CONFIG_FSCACHE + if (cookie != FSCACHE_NEGATIVE_COOKIE) + return __fscache_pin_cookie(cookie); +#endif + return -ENOBUFS; +} + +static inline +void fscache_unpin_cookie(struct fscache_cookie *cookie) +{ +#ifdef CONFIG_FSCACHE + if (cookie != FSCACHE_NEGATIVE_COOKIE) + __fscache_unpin_cookie(cookie); +#endif +} + +/*****************************************************************************/ +/* + * fscache cached network filesystem type + * - name, version and ops must be filled in before registration + * - all other fields will be set during registration + */ +struct fscache_netfs +{ + uint32_t version; /* indexing version */ + const char *name; /* filesystem name */ + struct fscache_cookie *primary_index; + struct fscache_netfs_operations *ops; + struct list_head link; /* internal link */ +}; + +struct fscache_netfs_operations +{ +}; + +#ifdef CONFIG_FSCACHE +extern int __fscache_register_netfs(struct fscache_netfs *netfs); +extern void __fscache_unregister_netfs(struct fscache_netfs *netfs); +#endif + +static inline +int fscache_register_netfs(struct fscache_netfs *netfs) +{ +#ifdef CONFIG_FSCACHE + return __fscache_register_netfs(netfs); +#else + return 0; +#endif +} + +static inline +void fscache_unregister_netfs(struct fscache_netfs *netfs) +{ +#ifdef CONFIG_FSCACHE + __fscache_unregister_netfs(netfs); +#endif +} + +/*****************************************************************************/ +/* + * look up a cache tag + * - cache tags are used to select specific caches in which to cache indexes + */ +#ifdef CONFIG_FSCACHE +extern struct fscache_cache_tag *__fscache_lookup_cache_tag(const char *name); +extern void __fscache_release_cache_tag(struct fscache_cache_tag *tag); +#endif + +static inline +struct fscache_cache_tag *fscache_lookup_cache_tag(const char *name) +{ +#ifdef CONFIG_FSCACHE + return __fscache_lookup_cache_tag(name); +#else + return NULL; +#endif +} + +static inline +void fscache_release_cache_tag(struct fscache_cache_tag *tag) +{ +#ifdef CONFIG_FSCACHE + __fscache_release_cache_tag(tag); +#endif +} + +/*****************************************************************************/ +/* + * set the data size on a cached object + * - no pages beyond the end of the object will be accessible + * - returns -ENOBUFS if the file is not backed + * - returns -ENOSPC if a pinned file of that size can't be stored + * - returns 0 if okay + */ +#ifdef CONFIG_FSCACHE +extern int __fscache_set_i_size(struct fscache_cookie *cookie, loff_t i_size); +#endif + +static inline +int fscache_set_i_size(struct fscache_cookie *cookie, loff_t i_size) +{ +#ifdef CONFIG_FSCACHE + if (cookie != FSCACHE_NEGATIVE_COOKIE) + return __fscache_set_i_size(cookie, i_size); +#endif + return -ENOBUFS; +} + +/*****************************************************************************/ +/* + * reserve data space for a cached object + * - returns -ENOBUFS if the file is not backed + * - returns -ENOSPC if there isn't enough space to honour the reservation + * - returns 0 if okay + */ +#ifdef CONFIG_FSCACHE +extern int __fscache_reserve_space(struct fscache_cookie *cookie, loff_t size); +#endif + +static inline +int fscache_reserve_space(struct fscache_cookie *cookie, loff_t size) +{ +#ifdef CONFIG_FSCACHE + if (cookie != FSCACHE_NEGATIVE_COOKIE) + return __fscache_reserve_space(cookie, size); +#endif + return -ENOBUFS; +} + +/*****************************************************************************/ +/* + * read a page from the cache or allocate a block in which to store it + * - if the page is not backed by a file: + * - -ENOBUFS will be returned and nothing more will be done + * - else if the page is backed by a block in the cache: + * - a read will be started which will call end_io_func on completion + * - else if the page is unbacked: + * - a block will be allocated + * - -ENODATA will be returned + */ +#ifdef CONFIG_FSCACHE +extern int __fscache_read_or_alloc_page(struct fscache_cookie *cookie, + struct page *page, + fscache_rw_complete_t end_io_func, + void *end_io_data, + gfp_t gfp); +#endif + +static inline +int fscache_read_or_alloc_page(struct fscache_cookie *cookie, + struct page *page, + fscache_rw_complete_t end_io_func, + void *end_io_data, + gfp_t gfp) +{ +#ifdef CONFIG_FSCACHE + if (cookie != FSCACHE_NEGATIVE_COOKIE) + return __fscache_read_or_alloc_page(cookie, page, end_io_func, + end_io_data, gfp); +#endif + return -ENOBUFS; +} + +#ifdef CONFIG_FSCACHE +extern int __fscache_read_or_alloc_pages(struct fscache_cookie *cookie, + struct address_space *mapping, + struct list_head *pages, + unsigned *nr_pages, + fscache_rw_complete_t end_io_func, + void *end_io_data, + gfp_t gfp); +#endif + +static inline +int fscache_read_or_alloc_pages(struct fscache_cookie *cookie, + struct address_space *mapping, + struct list_head *pages, + unsigned *nr_pages, + fscache_rw_complete_t end_io_func, + void *end_io_data, + gfp_t gfp) +{ +#ifdef CONFIG_FSCACHE + if (cookie != FSCACHE_NEGATIVE_COOKIE) + return __fscache_read_or_alloc_pages(cookie, mapping, pages, + nr_pages, end_io_func, + end_io_data, gfp); +#endif + return -ENOBUFS; +} + +/* + * allocate a block in which to store a page + * - if the page is not backed by a file: + * - -ENOBUFS will be returned and nothing more will be done + * - else + * - a block will be allocated if there isn't one + * - 0 will be returned + */ +#ifdef CONFIG_FSCACHE +extern int __fscache_alloc_page(struct fscache_cookie *cookie, + struct page *page, + gfp_t gfp); +#endif + +static inline +int fscache_alloc_page(struct fscache_cookie *cookie, + struct page *page, + gfp_t gfp) +{ +#ifdef CONFIG_FSCACHE + if (cookie != FSCACHE_NEGATIVE_COOKIE) + return __fscache_alloc_page(cookie, page, gfp); +#endif + return -ENOBUFS; +} + +/* + * request a page be stored in the cache + * - this request may be ignored if no cache block is currently allocated, in + * which case it: + * - returns -ENOBUFS + * - if a cache block was already allocated: + * - a BIO will be dispatched to write the page (end_io_func will be called + * from the completion function) + * - returns 0 + */ +#ifdef CONFIG_FSCACHE +extern int __fscache_write_page(struct fscache_cookie *cookie, + struct page *page, + fscache_rw_complete_t end_io_func, + void *end_io_data, + gfp_t gfp); + +extern int __fscache_write_pages(struct fscache_cookie *cookie, + struct pagevec *pagevec, + fscache_rw_complete_t end_io_func, + void *end_io_data, + gfp_t gfp); +#endif + +static inline +int fscache_write_page(struct fscache_cookie *cookie, + struct page *page, + fscache_rw_complete_t end_io_func, + void *end_io_data, + gfp_t gfp) +{ +#ifdef CONFIG_FSCACHE + if (cookie != FSCACHE_NEGATIVE_COOKIE) + return __fscache_write_page(cookie, page, end_io_func, + end_io_data, gfp); +#endif + return -ENOBUFS; +} + +static inline +int fscache_write_pages(struct fscache_cookie *cookie, + struct pagevec *pagevec, + fscache_rw_complete_t end_io_func, + void *end_io_data, + gfp_t gfp) +{ +#ifdef CONFIG_FSCACHE + if (cookie != FSCACHE_NEGATIVE_COOKIE) + return __fscache_write_pages(cookie, pagevec, end_io_func, + end_io_data, gfp); +#endif + return -ENOBUFS; +} + +/* + * indicate that caching is no longer required on a page + * - note: cannot cancel any outstanding BIOs between this page and the cache + */ +#ifdef CONFIG_FSCACHE +extern void __fscache_uncache_page(struct fscache_cookie *cookie, + struct page *page); +extern void __fscache_uncache_pages(struct fscache_cookie *cookie, + struct pagevec *pagevec); +#endif + +static inline +void fscache_uncache_page(struct fscache_cookie *cookie, + struct page *page) +{ +#ifdef CONFIG_FSCACHE + if (cookie != FSCACHE_NEGATIVE_COOKIE) + __fscache_uncache_page(cookie, page); +#endif +} + +static inline +void fscache_uncache_pagevec(struct fscache_cookie *cookie, + struct pagevec *pagevec) +{ +#ifdef CONFIG_FSCACHE + if (cookie != FSCACHE_NEGATIVE_COOKIE) + __fscache_uncache_pages(cookie, pagevec); +#endif +} + +#endif /* _LINUX_FSCACHE_H */