lkml.org 
[lkml]   [2022]   [Apr]   [21]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
From
SubjectRe: [PATCH v9 08/21] cachefiles: document on-demand read mode
Date
Jeffle Xu <jefflexu@linux.alibaba.com> wrote:

> +When working in its original mode, cachefiles mainly

I'd delete "mainly" there.

> serves as a local cache
> +for a remote networking fs - while in on-demand read mode, cachefiles can boost
> +the scenario where on-demand read semantics is

is -> are.

> +The essential difference between these two modes is that, in original mode,
> +when a cache miss occurs, the netfs will fetch the data from the remote server
> +and then write it to the cache file. With on-demand read mode, however,
> +fetching the data and writing it into the cache is delegated to a user daemon.

The starting sentence seems off. How about:

The essential difference between these two modes is seen when a cache miss
occurs: In the original mode, the netfs will fetch the data from the remote
server and then write it to the cache file; in on-demand read mode, fetching
data and writing it into the cache is delegated to a user daemon.

> +Protocol Communication
> +----------------------
> +
> +The on-demand read mode relies on

relies on -> uses

> a simple protocol used

Delete "used".

> for communication
> +between kernel and user daemon. The protocol can be modeled as::
> +
> + kernel --[request]--> user daemon --[reply]--> kernel
> +
> +The cachefiles kernel module will send requests to the user daemon when needed.
> +The user daemon needs to

needs to -> should

> poll on

poll on -> poll

> the devnode ('/dev/cachefiles') to check if
> +there's a pending request to be processed. A POLLIN event will be returned
> +when there's a pending request.
> +
> +The user daemon then reads the devnode to fetch a request and process it
> +accordingly.

Reading the devnode doesn't process the request, so I think something like:

"... and process it accordingly" -> "... that it can then process."

or:

"... and process it accordingly" -> "... to process."

> It is worth noting

"It should be noted"

> that each read only gets one request. When

... it has ...

> +finished processing the request, the user daemon needs to

needs to -> should write

> write the reply to
> +the devnode.
> +
> +Each request starts with a message header of the form::
> +
> + struct cachefiles_msg {
> + __u32 msg_id;
> + __u32 opcode;
> + __u32 len;
> + __u32 object_id;
> + __u8 data[];
> + };
> +
> + where:
> +
> + * ``msg_id`` is a unique ID identifying this request among all pending
> + requests.
> +
> + * ``opcode`` indicates the type of this request.
> +
> + * ``object_id`` is a unique ID identifying the cache file operated on.
> +
> + * ``data`` indicates the payload of this request.
> +
> + * ``len`` indicates the whole length of this request, including the
> + header and following type-specific payload.
> +
> +
> +Turn on On-demand Mode

Turning on

> +----------------------
> +
> +An optional parameter is added

is added -> becomes available

> to the "bind" command::
> +
> + bind [ondemand]
> +
> +When the "bind" command takes without

takes without -> is given no

> argument, it defaults to the original
> +mode. When the "bind" command is given

When it is given

> the "ondemand" argument, i.e.
> +"bind ondemand", on-demand read mode will be enabled.
> +
> +
> +The OPEN Request
> +----------------
> +
> +When the netfs opens a cache file for the first time, a request with the
> +CACHEFILES_OP_OPEN opcode, a.k.a an OPEN request will be sent to the user
> +daemon. The payload format is of the form::
> +
> + struct cachefiles_open {
> + __u32 volume_key_size;
> + __u32 cookie_key_size;
> + __u32 fd;
> + __u32 flags;
> + __u8 data[];
> + };
> +
> + where:
> +
> + * ``data`` contains the volume_key followed directly by the cookie_key.
> + The volume key is a NUL-terminated string; the cookie key is binary
> + data.
> +
> + * ``volume_key_size`` indicates the size of the volume key in bytes.
> +
> + * ``cookie_key_size`` indicates the size of the cookie key in bytes.
> +
> + * ``fd`` indicates an anonymous fd referring to the cache file, through
> + which the user daemon can perform write/llseek file operations on the
> + cache file.
> +
> +
> +The user daemon is able to distinguish the requested cache file with the given
> +(volume_key, cookie_key) pair.

"The user daemon can use the given (volume_key, cookie_key) pair to
distinguish the requested cache file." might sound better.

> Each cache file has a unique object_id, while it
> +may have multiple anonymous fds. The user daemon may duplicate anonymous fds
> +from the initial anonymous fd indicated by the @fd field through dup(). Thus
> +each object_id can be mapped to multiple anonymous fds, while the usr daemon
> +itself needs to maintain the mapping.
> +
> +With the given anonymous fd, the user daemon can fetch data and write it to the
> +cache file in the background, even when kernel has not triggered a cache miss
> +yet.
> +
> +The user daemon should complete the READ request

READ request -> OPEN request?

> by issuing a "copen" (complete
> +open) command on the devnode::
> +
> + copen <msg_id>,<cache_size>
> +
> + * ``msg_id`` must match the msg_id field of the previous OPEN request.
> +
> + * When >= 0, ``cache_size`` indicates the size of the cache file;
> + when < 0, ``cache_size`` indicates the

the -> any

> error code ecountered

encountered

> by the
> + user daemon.
> +
> +
> +The CLOSE Request
> +-----------------
> +
> +When a cookie withdrawn, a CLOSE request (opcode CACHEFILES_OP_CLOSE) will be
> +sent to the user daemon. It will notify

It will notify -> This tells

> the user daemon to close all anonymous
> +fds associated with the given object_id. The CLOSE request has no extea

extra

> +payload.
> +
> +
> +The READ Request
> +----------------
> +
> +When on-demand read mode is turned on, and a cache miss encountered,

"When a cache miss is encountered in on-demand read mode,"

> the kernel
> +will send a READ request (opcode CACHEFILES_OP_READ) to the user daemon. This
> +will tell

will tell -> tells/asks

> the user daemon to fetch data

data -> the contents

> of the requested file range. The payload
> +is of the form::
> +
> + struct cachefiles_read {
> + __u64 off;
> + __u64 len;
> + };
> +
> + where:
> +
> + * ``off`` indicates the starting offset of the requested file range.
> +
> + * ``len`` indicates the length of the requested file range.
> +
> +
> +When receiving

receiving -> it receives

> a READ request, the user daemon needs to

needs to -> should

> fetch the

requested

> data of the
> +requested file range,

"of the requested file range," -> "" (including the comma, I think)

> and then

"then" -> ""

> write it to the cache file identified by
> +object_id.
> +
> +To finish

When it has finished

> processing the READ request, the user daemon should reply with

with -> by using

> the
> +CACHEFILES_IOC_CREAD ioctl on one of the anonymous fds associated with the given
> +object_id

given object_id -> object_id given

> in the READ request. The ioctl is of the form::
> +
> + ioctl(fd, CACHEFILES_IOC_CREAD, msg_id);
> +
> + * ``fd`` is one of the anonymous fds associated with the given object_id
> + in the READ request.

the given object_id in the READ request -> object_id

> +
> + * ``msg_id`` must match the msg_id field of the previous READ request.

By "previous READ request" is this referring to something different to "the
READ request" you mentioned against the fd parameter?

David

\
 
 \ /
  Last update: 2022-04-21 16:49    [W:0.276 / U:0.184 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site