blob: 5f757c8cf979524b8fc8be321b77660a97cdc941 [file] [log] [blame]
NeilBrown49121472006-03-27 01:15:12 -08001 This document gives a brief introduction to the caching
Linus Torvalds1da177e2005-04-16 15:20:36 -07002mechanisms in the sunrpc layer that is used, in particular,
3for NFS authentication.
4
5CACHES
6======
7The caching replaces the old exports table and allows for
8a wide variety of values to be caches.
9
10There are a number of caches that are similar in structure though
11quite possibly very different in content and use. There is a corpus
12of common code for managing these caches.
13
14Examples of caches that are likely to be needed are:
15 - mapping from IP address to client name
16 - mapping from client name and filesystem to export options
17 - mapping from UID to list of GIDs, to work around NFS's limitation
18 of 16 gids.
19 - mappings between local UID/GID and remote UID/GID for sites that
20 do not have uniform uid assignment
21 - mapping from network identify to public key for crypto authentication.
22
23The common code handles such things as:
24 - general cache lookup with correct locking
25 - supporting 'NEGATIVE' as well as positive entries
26 - allowing an EXPIRED time on cache items, and removing
27 items after they expire, and are no longe in-use.
Linus Torvalds1da177e2005-04-16 15:20:36 -070028 - making requests to user-space to fill in cache entries
29 - allowing user-space to directly set entries in the cache
30 - delaying RPC requests that depend on as-yet incomplete
31 cache entries, and replaying those requests when the cache entry
32 is complete.
NeilBrown49121472006-03-27 01:15:12 -080033 - clean out old entries as they expire.
Linus Torvalds1da177e2005-04-16 15:20:36 -070034
35Creating a Cache
36----------------
37
NeilBrown49121472006-03-27 01:15:12 -0800381/ A cache needs a datum to store. This is in the form of a
Linus Torvalds1da177e2005-04-16 15:20:36 -070039 structure definition that must contain a
40 struct cache_head
41 as an element, usually the first.
42 It will also contain a key and some content.
43 Each cache element is reference counted and contains
44 expiry and update times for use in cache management.
452/ A cache needs a "cache_detail" structure that
NeilBrown49121472006-03-27 01:15:12 -080046 describes the cache. This stores the hash table, some
47 parameters for cache management, and some operations detailing how
48 to work with particular cache items.
49 The operations requires are:
50 struct cache_head *alloc(void)
51 This simply allocates appropriate memory and returns
52 a pointer to the cache_detail embedded within the
53 structure
54 void cache_put(struct kref *)
55 This is called when the last reference to an item is
56 is dropped. The pointer passed is to the 'ref' field
57 in the cache_head. cache_put should release any
58 references create by 'cache_init' and, if CACHE_VALID
59 is set, any references created by cache_update.
60 It should then release the memory allocated by
61 'alloc'.
62 int match(struct cache_head *orig, struct cache_head *new)
63 test if the keys in the two structures match. Return
64 1 if they do, 0 if they don't.
65 void init(struct cache_head *orig, struct cache_head *new)
66 Set the 'key' fields in 'new' from 'orig'. This may
67 include taking references to shared objects.
68 void update(struct cache_head *orig, struct cache_head *new)
69 Set the 'content' fileds in 'new' from 'orig'.
70 int cache_show(struct seq_file *m, struct cache_detail *cd,
71 struct cache_head *h)
72 Optional. Used to provide a /proc file that lists the
73 contents of a cache. This should show one item,
74 usually on just one line.
75 int cache_request(struct cache_detail *cd, struct cache_head *h,
76 char **bpp, int *blen)
77 Format a request to be send to user-space for an item
78 to be instantiated. *bpp is a buffer of size *blen.
79 bpp should be moved forward over the encoded message,
80 and *blen should be reduced to show how much free
81 space remains. Return 0 on success or <0 if not
82 enough room or other problem.
83 int cache_parse(struct cache_detail *cd, char *buf, int len)
84 A message from user space has arrived to fill out a
85 cache entry. It is in 'buf' of length 'len'.
86 cache_parse should parse this, find the item in the
87 cache with sunrpc_cache_lookup, and update the item
88 with sunrpc_cache_update.
89
90
913/ A cache needs to be registered using cache_register(). This
92 includes it on a list of caches that will be regularly
93 cleaned to discard old data.
94
Linus Torvalds1da177e2005-04-16 15:20:36 -070095Using a cache
96-------------
97
NeilBrown49121472006-03-27 01:15:12 -080098To find a value in a cache, call sunrpc_cache_lookup passing a pointer
99to the cache_head in a sample item with the 'key' fields filled in.
100This will be passed to ->match to identify the target entry. If no
101entry is found, a new entry will be create, added to the cache, and
102marked as not containing valid data.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700103
NeilBrown49121472006-03-27 01:15:12 -0800104The item returned is typically passed to cache_check which will check
105if the data is valid, and may initiate an up-call to get fresh data.
106cache_check will return -ENOENT in the entry is negative or if an up
107call is needed but not possible, -EAGAIN if an upcall is pending,
108or 0 if the data is valid;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700109
110cache_check can be passed a "struct cache_req *". This structure is
111typically embedded in the actual request and can be used to create a
112deferred copy of the request (struct cache_deferred_req). This is
113done when the found cache item is not uptodate, but the is reason to
114believe that userspace might provide information soon. When the cache
115item does become valid, the deferred copy of the request will be
116revisited (->revisit). It is expected that this method will
117reschedule the request for processing.
118
NeilBrown49121472006-03-27 01:15:12 -0800119The value returned by sunrpc_cache_lookup can also be passed to
120sunrpc_cache_update to set the content for the item. A second item is
121passed which should hold the content. If the item found by _lookup
122has valid data, then it is discarded and a new item is created. This
123saves any user of an item from worrying about content changing while
124it is being inspected. If the item found by _lookup does not contain
125valid data, then the content is copied across and CACHE_VALID is set.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700126
127Populating a cache
128------------------
129
130Each cache has a name, and when the cache is registered, a directory
131with that name is created in /proc/net/rpc
132
133This directory contains a file called 'channel' which is a channel
134for communicating between kernel and user for populating the cache.
135This directory may later contain other files of interacting
136with the cache.
137
138The 'channel' works a bit like a datagram socket. Each 'write' is
139passed as a whole to the cache for parsing and interpretation.
140Each cache can treat the write requests differently, but it is
141expected that a message written will contain:
142 - a key
143 - an expiry time
144 - a content.
145with the intention that an item in the cache with the give key
146should be create or updated to have the given content, and the
147expiry time should be set on that item.
148
149Reading from a channel is a bit more interesting. When a cache
NeilBrown49121472006-03-27 01:15:12 -0800150lookup fails, or when it succeeds but finds an entry that may soon
151expire, a request is lodged for that cache item to be updated by
Linus Torvalds1da177e2005-04-16 15:20:36 -0700152user-space. These requests appear in the channel file.
153
154Successive reads will return successive requests.
155If there are no more requests to return, read will return EOF, but a
156select or poll for read will block waiting for another request to be
157added.
158
159Thus a user-space helper is likely to:
160 open the channel.
161 select for readable
162 read a request
163 write a response
164 loop.
165
NeilBrown49121472006-03-27 01:15:12 -0800166If it dies and needs to be restarted, any requests that have not been
Linus Torvalds1da177e2005-04-16 15:20:36 -0700167answered will still appear in the file and will be read by the new
168instance of the helper.
169
170Each cache should define a "cache_parse" method which takes a message
171written from user-space and processes it. It should return an error
172(which propagates back to the write syscall) or 0.
173
174Each cache should also define a "cache_request" method which
175takes a cache item and encodes a request into the buffer
176provided.
177
Linus Torvalds1da177e2005-04-16 15:20:36 -0700178Note: If a cache has no active readers on the channel, and has had not
179active readers for more than 60 seconds, further requests will not be
NeilBrown49121472006-03-27 01:15:12 -0800180added to the channel but instead all lookups that do not find a valid
Linus Torvalds1da177e2005-04-16 15:20:36 -0700181entry will fail. This is partly for backward compatibility: The
182previous nfs exports table was deemed to be authoritative and a
183failed lookup meant a definite 'no'.
184
185request/response format
186-----------------------
187
188While each cache is free to use it's own format for requests
NeilBrown49121472006-03-27 01:15:12 -0800189and responses over channel, the following is recommended as
Linus Torvalds1da177e2005-04-16 15:20:36 -0700190appropriate and support routines are available to help:
191Each request or response record should be printable ASCII
192with precisely one newline character which should be at the end.
193Fields within the record should be separated by spaces, normally one.
194If spaces, newlines, or nul characters are needed in a field they
NeilBrown49121472006-03-27 01:15:12 -0800195much be quoted. two mechanisms are available:
Linus Torvalds1da177e2005-04-16 15:20:36 -07001961/ If a field begins '\x' then it must contain an even number of
197 hex digits, and pairs of these digits provide the bytes in the
198 field.
1992/ otherwise a \ in the field must be followed by 3 octal digits
200 which give the code for a byte. Other characters are treated
NeilBrown49121472006-03-27 01:15:12 -0800201 as them selves. At the very least, space, newline, nul, and
Linus Torvalds1da177e2005-04-16 15:20:36 -0700202 '\' must be quoted in this way.