lkml.org 
[lkml]   [2008]   [Apr]   [7]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH] Documentation: move rpc-cache.txt to filesystems/
    Date
    This file is nfs-related.  (Maybe Documentation/filesystems/ would
    benefit from a separate nfs/ directory at some point.)

    Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
    ---
    Documentation/00-INDEX | 2 -
    Documentation/filesystems/00-INDEX | 2 +
    Documentation/filesystems/rpc-cache.txt | 202 +++++++++++++++++++++++++++++++
    Documentation/rpc-cache.txt | 202 -------------------------------
    4 files changed, 204 insertions(+), 204 deletions(-)
    create mode 100644 Documentation/filesystems/rpc-cache.txt
    delete mode 100644 Documentation/rpc-cache.txt

    diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
    index 08a39cd..e8fb246 100644
    --- a/Documentation/00-INDEX
    +++ b/Documentation/00-INDEX
    @@ -319,8 +319,6 @@ robust-futexes.txt
    - a description of what robust futexes are.
    rocket.txt
    - info on the Comtrol RocketPort multiport serial driver.
    -rpc-cache.txt
    - - introduction to the caching mechanisms in the sunrpc layer.
    rt-mutex-design.txt
    - description of the RealTime mutex implementation design.
    rt-mutex.txt
    diff --git a/Documentation/filesystems/00-INDEX b/Documentation/filesystems/00-INDEX
    index b1b523b..a2e5d5d 100644
    --- a/Documentation/filesystems/00-INDEX
    +++ b/Documentation/filesystems/00-INDEX
    @@ -84,6 +84,8 @@ relay.txt
    - info on relay, for efficient streaming from kernel to user space.
    romfs.txt
    - description of the ROMFS filesystem.
    +rpc-cache.txt
    + - introduction to the caching mechanisms in the sunrpc layer.
    sharedsubtree.txt
    - a description of shared subtrees for namespaces.
    smbfs.txt
    diff --git a/Documentation/filesystems/rpc-cache.txt b/Documentation/filesystems/rpc-cache.txt
    new file mode 100644
    index 0000000..8a382be
    --- /dev/null
    +++ b/Documentation/filesystems/rpc-cache.txt
    @@ -0,0 +1,202 @@
    + This document gives a brief introduction to the caching
    +mechanisms in the sunrpc layer that is used, in particular,
    +for NFS authentication.
    +
    +CACHES
    +======
    +The caching replaces the old exports table and allows for
    +a wide variety of values to be caches.
    +
    +There are a number of caches that are similar in structure though
    +quite possibly very different in content and use. There is a corpus
    +of common code for managing these caches.
    +
    +Examples of caches that are likely to be needed are:
    + - mapping from IP address to client name
    + - mapping from client name and filesystem to export options
    + - mapping from UID to list of GIDs, to work around NFS's limitation
    + of 16 gids.
    + - mappings between local UID/GID and remote UID/GID for sites that
    + do not have uniform uid assignment
    + - mapping from network identify to public key for crypto authentication.
    +
    +The common code handles such things as:
    + - general cache lookup with correct locking
    + - supporting 'NEGATIVE' as well as positive entries
    + - allowing an EXPIRED time on cache items, and removing
    + items after they expire, and are no longer in-use.
    + - making requests to user-space to fill in cache entries
    + - allowing user-space to directly set entries in the cache
    + - delaying RPC requests that depend on as-yet incomplete
    + cache entries, and replaying those requests when the cache entry
    + is complete.
    + - clean out old entries as they expire.
    +
    +Creating a Cache
    +----------------
    +
    +1/ A cache needs a datum to store. This is in the form of a
    + structure definition that must contain a
    + struct cache_head
    + as an element, usually the first.
    + It will also contain a key and some content.
    + Each cache element is reference counted and contains
    + expiry and update times for use in cache management.
    +2/ A cache needs a "cache_detail" structure that
    + describes the cache. This stores the hash table, some
    + parameters for cache management, and some operations detailing how
    + to work with particular cache items.
    + The operations requires are:
    + struct cache_head *alloc(void)
    + This simply allocates appropriate memory and returns
    + a pointer to the cache_detail embedded within the
    + structure
    + void cache_put(struct kref *)
    + This is called when the last reference to an item is
    + dropped. The pointer passed is to the 'ref' field
    + in the cache_head. cache_put should release any
    + references create by 'cache_init' and, if CACHE_VALID
    + is set, any references created by cache_update.
    + It should then release the memory allocated by
    + 'alloc'.
    + int match(struct cache_head *orig, struct cache_head *new)
    + test if the keys in the two structures match. Return
    + 1 if they do, 0 if they don't.
    + void init(struct cache_head *orig, struct cache_head *new)
    + Set the 'key' fields in 'new' from 'orig'. This may
    + include taking references to shared objects.
    + void update(struct cache_head *orig, struct cache_head *new)
    + Set the 'content' fileds in 'new' from 'orig'.
    + int cache_show(struct seq_file *m, struct cache_detail *cd,
    + struct cache_head *h)
    + Optional. Used to provide a /proc file that lists the
    + contents of a cache. This should show one item,
    + usually on just one line.
    + int cache_request(struct cache_detail *cd, struct cache_head *h,
    + char **bpp, int *blen)
    + Format a request to be send to user-space for an item
    + to be instantiated. *bpp is a buffer of size *blen.
    + bpp should be moved forward over the encoded message,
    + and *blen should be reduced to show how much free
    + space remains. Return 0 on success or <0 if not
    + enough room or other problem.
    + int cache_parse(struct cache_detail *cd, char *buf, int len)
    + A message from user space has arrived to fill out a
    + cache entry. It is in 'buf' of length 'len'.
    + cache_parse should parse this, find the item in the
    + cache with sunrpc_cache_lookup, and update the item
    + with sunrpc_cache_update.
    +
    +
    +3/ A cache needs to be registered using cache_register(). This
    + includes it on a list of caches that will be regularly
    + cleaned to discard old data.
    +
    +Using a cache
    +-------------
    +
    +To find a value in a cache, call sunrpc_cache_lookup passing a pointer
    +to the cache_head in a sample item with the 'key' fields filled in.
    +This will be passed to ->match to identify the target entry. If no
    +entry is found, a new entry will be create, added to the cache, and
    +marked as not containing valid data.
    +
    +The item returned is typically passed to cache_check which will check
    +if the data is valid, and may initiate an up-call to get fresh data.
    +cache_check will return -ENOENT in the entry is negative or if an up
    +call is needed but not possible, -EAGAIN if an upcall is pending,
    +or 0 if the data is valid;
    +
    +cache_check can be passed a "struct cache_req *". This structure is
    +typically embedded in the actual request and can be used to create a
    +deferred copy of the request (struct cache_deferred_req). This is
    +done when the found cache item is not uptodate, but the is reason to
    +believe that userspace might provide information soon. When the cache
    +item does become valid, the deferred copy of the request will be
    +revisited (->revisit). It is expected that this method will
    +reschedule the request for processing.
    +
    +The value returned by sunrpc_cache_lookup can also be passed to
    +sunrpc_cache_update to set the content for the item. A second item is
    +passed which should hold the content. If the item found by _lookup
    +has valid data, then it is discarded and a new item is created. This
    +saves any user of an item from worrying about content changing while
    +it is being inspected. If the item found by _lookup does not contain
    +valid data, then the content is copied across and CACHE_VALID is set.
    +
    +Populating a cache
    +------------------
    +
    +Each cache has a name, and when the cache is registered, a directory
    +with that name is created in /proc/net/rpc
    +
    +This directory contains a file called 'channel' which is a channel
    +for communicating between kernel and user for populating the cache.
    +This directory may later contain other files of interacting
    +with the cache.
    +
    +The 'channel' works a bit like a datagram socket. Each 'write' is
    +passed as a whole to the cache for parsing and interpretation.
    +Each cache can treat the write requests differently, but it is
    +expected that a message written will contain:
    + - a key
    + - an expiry time
    + - a content.
    +with the intention that an item in the cache with the give key
    +should be create or updated to have the given content, and the
    +expiry time should be set on that item.
    +
    +Reading from a channel is a bit more interesting. When a cache
    +lookup fails, or when it succeeds but finds an entry that may soon
    +expire, a request is lodged for that cache item to be updated by
    +user-space. These requests appear in the channel file.
    +
    +Successive reads will return successive requests.
    +If there are no more requests to return, read will return EOF, but a
    +select or poll for read will block waiting for another request to be
    +added.
    +
    +Thus a user-space helper is likely to:
    + open the channel.
    + select for readable
    + read a request
    + write a response
    + loop.
    +
    +If it dies and needs to be restarted, any requests that have not been
    +answered will still appear in the file and will be read by the new
    +instance of the helper.
    +
    +Each cache should define a "cache_parse" method which takes a message
    +written from user-space and processes it. It should return an error
    +(which propagates back to the write syscall) or 0.
    +
    +Each cache should also define a "cache_request" method which
    +takes a cache item and encodes a request into the buffer
    +provided.
    +
    +Note: If a cache has no active readers on the channel, and has had not
    +active readers for more than 60 seconds, further requests will not be
    +added to the channel but instead all lookups that do not find a valid
    +entry will fail. This is partly for backward compatibility: The
    +previous nfs exports table was deemed to be authoritative and a
    +failed lookup meant a definite 'no'.
    +
    +request/response format
    +-----------------------
    +
    +While each cache is free to use it's own format for requests
    +and responses over channel, the following is recommended as
    +appropriate and support routines are available to help:
    +Each request or response record should be printable ASCII
    +with precisely one newline character which should be at the end.
    +Fields within the record should be separated by spaces, normally one.
    +If spaces, newlines, or nul characters are needed in a field they
    +much be quoted. two mechanisms are available:
    +1/ If a field begins '\x' then it must contain an even number of
    + hex digits, and pairs of these digits provide the bytes in the
    + field.
    +2/ otherwise a \ in the field must be followed by 3 octal digits
    + which give the code for a byte. Other characters are treated
    + as them selves. At the very least, space, newline, nul, and
    + '\' must be quoted in this way.
    diff --git a/Documentation/rpc-cache.txt b/Documentation/rpc-cache.txt
    deleted file mode 100644
    index 8a382be..0000000
    --- a/Documentation/rpc-cache.txt
    +++ /dev/null
    @@ -1,202 +0,0 @@
    - This document gives a brief introduction to the caching
    -mechanisms in the sunrpc layer that is used, in particular,
    -for NFS authentication.
    -
    -CACHES
    -======
    -The caching replaces the old exports table and allows for
    -a wide variety of values to be caches.
    -
    -There are a number of caches that are similar in structure though
    -quite possibly very different in content and use. There is a corpus
    -of common code for managing these caches.
    -
    -Examples of caches that are likely to be needed are:
    - - mapping from IP address to client name
    - - mapping from client name and filesystem to export options
    - - mapping from UID to list of GIDs, to work around NFS's limitation
    - of 16 gids.
    - - mappings between local UID/GID and remote UID/GID for sites that
    - do not have uniform uid assignment
    - - mapping from network identify to public key for crypto authentication.
    -
    -The common code handles such things as:
    - - general cache lookup with correct locking
    - - supporting 'NEGATIVE' as well as positive entries
    - - allowing an EXPIRED time on cache items, and removing
    - items after they expire, and are no longer in-use.
    - - making requests to user-space to fill in cache entries
    - - allowing user-space to directly set entries in the cache
    - - delaying RPC requests that depend on as-yet incomplete
    - cache entries, and replaying those requests when the cache entry
    - is complete.
    - - clean out old entries as they expire.
    -
    -Creating a Cache
    -----------------
    -
    -1/ A cache needs a datum to store. This is in the form of a
    - structure definition that must contain a
    - struct cache_head
    - as an element, usually the first.
    - It will also contain a key and some content.
    - Each cache element is reference counted and contains
    - expiry and update times for use in cache management.
    -2/ A cache needs a "cache_detail" structure that
    - describes the cache. This stores the hash table, some
    - parameters for cache management, and some operations detailing how
    - to work with particular cache items.
    - The operations requires are:
    - struct cache_head *alloc(void)
    - This simply allocates appropriate memory and returns
    - a pointer to the cache_detail embedded within the
    - structure
    - void cache_put(struct kref *)
    - This is called when the last reference to an item is
    - dropped. The pointer passed is to the 'ref' field
    - in the cache_head. cache_put should release any
    - references create by 'cache_init' and, if CACHE_VALID
    - is set, any references created by cache_update.
    - It should then release the memory allocated by
    - 'alloc'.
    - int match(struct cache_head *orig, struct cache_head *new)
    - test if the keys in the two structures match. Return
    - 1 if they do, 0 if they don't.
    - void init(struct cache_head *orig, struct cache_head *new)
    - Set the 'key' fields in 'new' from 'orig'. This may
    - include taking references to shared objects.
    - void update(struct cache_head *orig, struct cache_head *new)
    - Set the 'content' fileds in 'new' from 'orig'.
    - int cache_show(struct seq_file *m, struct cache_detail *cd,
    - struct cache_head *h)
    - Optional. Used to provide a /proc file that lists the
    - contents of a cache. This should show one item,
    - usually on just one line.
    - int cache_request(struct cache_detail *cd, struct cache_head *h,
    - char **bpp, int *blen)
    - Format a request to be send to user-space for an item
    - to be instantiated. *bpp is a buffer of size *blen.
    - bpp should be moved forward over the encoded message,
    - and *blen should be reduced to show how much free
    - space remains. Return 0 on success or <0 if not
    - enough room or other problem.
    - int cache_parse(struct cache_detail *cd, char *buf, int len)
    - A message from user space has arrived to fill out a
    - cache entry. It is in 'buf' of length 'len'.
    - cache_parse should parse this, find the item in the
    - cache with sunrpc_cache_lookup, and update the item
    - with sunrpc_cache_update.
    -
    -
    -3/ A cache needs to be registered using cache_register(). This
    - includes it on a list of caches that will be regularly
    - cleaned to discard old data.
    -
    -Using a cache
    --------------
    -
    -To find a value in a cache, call sunrpc_cache_lookup passing a pointer
    -to the cache_head in a sample item with the 'key' fields filled in.
    -This will be passed to ->match to identify the target entry. If no
    -entry is found, a new entry will be create, added to the cache, and
    -marked as not containing valid data.
    -
    -The item returned is typically passed to cache_check which will check
    -if the data is valid, and may initiate an up-call to get fresh data.
    -cache_check will return -ENOENT in the entry is negative or if an up
    -call is needed but not possible, -EAGAIN if an upcall is pending,
    -or 0 if the data is valid;
    -
    -cache_check can be passed a "struct cache_req *". This structure is
    -typically embedded in the actual request and can be used to create a
    -deferred copy of the request (struct cache_deferred_req). This is
    -done when the found cache item is not uptodate, but the is reason to
    -believe that userspace might provide information soon. When the cache
    -item does become valid, the deferred copy of the request will be
    -revisited (->revisit). It is expected that this method will
    -reschedule the request for processing.
    -
    -The value returned by sunrpc_cache_lookup can also be passed to
    -sunrpc_cache_update to set the content for the item. A second item is
    -passed which should hold the content. If the item found by _lookup
    -has valid data, then it is discarded and a new item is created. This
    -saves any user of an item from worrying about content changing while
    -it is being inspected. If the item found by _lookup does not contain
    -valid data, then the content is copied across and CACHE_VALID is set.
    -
    -Populating a cache
    -------------------
    -
    -Each cache has a name, and when the cache is registered, a directory
    -with that name is created in /proc/net/rpc
    -
    -This directory contains a file called 'channel' which is a channel
    -for communicating between kernel and user for populating the cache.
    -This directory may later contain other files of interacting
    -with the cache.
    -
    -The 'channel' works a bit like a datagram socket. Each 'write' is
    -passed as a whole to the cache for parsing and interpretation.
    -Each cache can treat the write requests differently, but it is
    -expected that a message written will contain:
    - - a key
    - - an expiry time
    - - a content.
    -with the intention that an item in the cache with the give key
    -should be create or updated to have the given content, and the
    -expiry time should be set on that item.
    -
    -Reading from a channel is a bit more interesting. When a cache
    -lookup fails, or when it succeeds but finds an entry that may soon
    -expire, a request is lodged for that cache item to be updated by
    -user-space. These requests appear in the channel file.
    -
    -Successive reads will return successive requests.
    -If there are no more requests to return, read will return EOF, but a
    -select or poll for read will block waiting for another request to be
    -added.
    -
    -Thus a user-space helper is likely to:
    - open the channel.
    - select for readable
    - read a request
    - write a response
    - loop.
    -
    -If it dies and needs to be restarted, any requests that have not been
    -answered will still appear in the file and will be read by the new
    -instance of the helper.
    -
    -Each cache should define a "cache_parse" method which takes a message
    -written from user-space and processes it. It should return an error
    -(which propagates back to the write syscall) or 0.
    -
    -Each cache should also define a "cache_request" method which
    -takes a cache item and encodes a request into the buffer
    -provided.
    -
    -Note: If a cache has no active readers on the channel, and has had not
    -active readers for more than 60 seconds, further requests will not be
    -added to the channel but instead all lookups that do not find a valid
    -entry will fail. This is partly for backward compatibility: The
    -previous nfs exports table was deemed to be authoritative and a
    -failed lookup meant a definite 'no'.
    -
    -request/response format
    ------------------------
    -
    -While each cache is free to use it's own format for requests
    -and responses over channel, the following is recommended as
    -appropriate and support routines are available to help:
    -Each request or response record should be printable ASCII
    -with precisely one newline character which should be at the end.
    -Fields within the record should be separated by spaces, normally one.
    -If spaces, newlines, or nul characters are needed in a field they
    -much be quoted. two mechanisms are available:
    -1/ If a field begins '\x' then it must contain an even number of
    - hex digits, and pairs of these digits provide the bytes in the
    - field.
    -2/ otherwise a \ in the field must be followed by 3 octal digits
    - which give the code for a byte. Other characters are treated
    - as them selves. At the very least, space, newline, nul, and
    - '\' must be quoted in this way.
    --
    1.5.5.rc1


    \
     
     \ /
      Last update: 2008-04-07 22:03    [W:0.053 / U:188.104 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site