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