blob: 2b5d4434fa5a5a7aa3ca5bdfe6c2e506fc43af84 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001This document gives a brief introduction to the caching
2mechanisms 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.
28
29 Future code extensions are expect to handle
30 - making requests to user-space to fill in cache entries
31 - allowing user-space to directly set entries in the cache
32 - delaying RPC requests that depend on as-yet incomplete
33 cache entries, and replaying those requests when the cache entry
34 is complete.
35 - maintaining last-access times on cache entries
36 - clean out old entries when the caches become full
37
38The code for performing a cache lookup is also common, but in the form
39of a template. i.e. a #define.
40Each cache defines a lookup function by using the DefineCacheLookup
41macro, or the simpler DefineSimpleCacheLookup macro
42
43Creating a Cache
44----------------
45
461/ A cache needs a datum to cache. This is in the form of a
47 structure definition that must contain a
48 struct cache_head
49 as an element, usually the first.
50 It will also contain a key and some content.
51 Each cache element is reference counted and contains
52 expiry and update times for use in cache management.
532/ A cache needs a "cache_detail" structure that
54 describes the cache. This stores the hash table, and some
55 parameters for cache management.
563/ A cache needs a lookup function. This is created using
57 the DefineCacheLookup macro. This lookup function is used both
58 to find entries and to update entries. The normal mode for
59 updating an entry is to replace the old entry with a new
60 entry. However it is possible to allow update-in-place
61 for those caches where it makes sense (no atomicity issues
62 or indirect reference counting issue)
634/ A cache needs to be registered using cache_register(). This
64 includes in on a list of caches that will be regularly
65 cleaned to discard old data. For this to work, some
66 thread must periodically call cache_clean
67
68Using a cache
69-------------
70
71To find a value in a cache, call the lookup function passing it a the
72datum which contains key, and possibly content, and a flag saying
73whether to update the cache with new data from the datum. Depending
74on how the cache lookup function was defined, it may take an extra
75argument to identify the particular cache in question.
76
77Except in cases of kmalloc failure, the lookup function
78will return a new datum which will store the key and
79may contain valid content, or may not.
80This datum is typically passed to cache_check which determines the
81validity of the datum and may later initiate an upcall to fill
82in the data.
83
84cache_check can be passed a "struct cache_req *". This structure is
85typically embedded in the actual request and can be used to create a
86deferred copy of the request (struct cache_deferred_req). This is
87done when the found cache item is not uptodate, but the is reason to
88believe that userspace might provide information soon. When the cache
89item does become valid, the deferred copy of the request will be
90revisited (->revisit). It is expected that this method will
91reschedule the request for processing.
92
93
94Populating a cache
95------------------
96
97Each cache has a name, and when the cache is registered, a directory
98with that name is created in /proc/net/rpc
99
100This directory contains a file called 'channel' which is a channel
101for communicating between kernel and user for populating the cache.
102This directory may later contain other files of interacting
103with the cache.
104
105The 'channel' works a bit like a datagram socket. Each 'write' is
106passed as a whole to the cache for parsing and interpretation.
107Each cache can treat the write requests differently, but it is
108expected that a message written will contain:
109 - a key
110 - an expiry time
111 - a content.
112with the intention that an item in the cache with the give key
113should be create or updated to have the given content, and the
114expiry time should be set on that item.
115
116Reading from a channel is a bit more interesting. When a cache
117lookup fail, or when it suceeds but finds an entry that may soon
118expiry, a request is lodged for that cache item to be updated by
119user-space. These requests appear in the channel file.
120
121Successive reads will return successive requests.
122If there are no more requests to return, read will return EOF, but a
123select or poll for read will block waiting for another request to be
124added.
125
126Thus a user-space helper is likely to:
127 open the channel.
128 select for readable
129 read a request
130 write a response
131 loop.
132
133If it dies and needs to be restarted, any requests that have not be
134answered will still appear in the file and will be read by the new
135instance of the helper.
136
137Each cache should define a "cache_parse" method which takes a message
138written from user-space and processes it. It should return an error
139(which propagates back to the write syscall) or 0.
140
141Each cache should also define a "cache_request" method which
142takes a cache item and encodes a request into the buffer
143provided.
144
145
146Note: If a cache has no active readers on the channel, and has had not
147active readers for more than 60 seconds, further requests will not be
148added to the channel but instead all looks that do not find a valid
149entry will fail. This is partly for backward compatibility: The
150previous nfs exports table was deemed to be authoritative and a
151failed lookup meant a definite 'no'.
152
153request/response format
154-----------------------
155
156While each cache is free to use it's own format for requests
157and responses over channel, the following is recommended are
158appropriate and support routines are available to help:
159Each request or response record should be printable ASCII
160with precisely one newline character which should be at the end.
161Fields within the record should be separated by spaces, normally one.
162If spaces, newlines, or nul characters are needed in a field they
163much be quotes. two mechanisms are available:
1641/ If a field begins '\x' then it must contain an even number of
165 hex digits, and pairs of these digits provide the bytes in the
166 field.
1672/ otherwise a \ in the field must be followed by 3 octal digits
168 which give the code for a byte. Other characters are treated
169 as them selves. At the very least, space, newlines nul, and
170 '\' must be quoted in this way.
171