Documentation/filesystems/coda.rst

4 Coda Kernel-Venus Interface
10    Coda -- this document describes the client kernel-Venus interface.
21 named Venus, as well as tools to manipulate ACLs, to log in, etc.  The
28   The Venus kernel interface
34   This document describes the communication between Venus and kernel
51      4.1 Data structures shared by the kernel and Venus
99   manager, Venus.
103   operating system. The operating system will communicate with Venus to
104   service the request for the process.  Venus manages a persistent
107   requests it receives from the operating system.  When Venus has
111   requests to limit the number of interactions with Venus.  Venus
116   kernel and Venus.  The definitions of so called upcalls and downcalls
121   The interface between the kernel and Venus is very similar to the BSD
130   Venus/Kernel protocol is necessary.  Also it came to light that other
133   to make future ports easier, communication between Venus and the
165   offered by the cache manager Venus.  When the replies from Venus have
171   must allow Venus to manage message traffic.  In particular Venus must
174   which does not block Venus since Venus must attend to other tasks even
180   between a user process and Venus, called the pioctl interface. The
183   Venus. Here the involvement of the kernel is minimal.  It identifies
184   the calling process and passes the information on to Venus.  When
185   Venus replies the response is passed back to the caller in unmodified
188   Finally Venus allows the kernel FS driver to cache the results from
190   and results in an efficient system.  However, Venus may acquire
192   information must be flushed or replaced. Venus then makes a downcall
205   At the lowest level the communication between Venus and the FS driver
207   requesting Coda file service and Venus relies on blocking and waking
209   on behalf of a process P, creates messages for Venus, awaits replies
214   Venus.
216   The FS Driver while servicing P makes upcalls to Venus.  Such an
217   upcall is dispatched to Venus by creating a message structure.  The
221   reply from Venus, there is a field for the size of the reply.  A flags
230   A facility must exist to notify Venus that the message has been
235   request routine must be suspended until Venus has replied.  Therefore
240   Venus detects the notification that a message has arrived, and the FS
241   driver allow Venus to retrieve the message with a getmsg_from_kernel
243   queue of processing messages and setting flags to READ.  Venus is
245   now returns and Venus processes the request.
247   At some later point the FS driver receives a message from Venus,
248   namely when Venus calls sendmsg_to_kernel.  At this moment the Coda FS
255      mode context of Venus) and the sendmsg_to_kernel call returns to
256      Venus.  The process P will be scheduled at some point and continues
258      from Venus.
260   *  The message is a ``downcall``.  A downcall is a request from Venus to
268   attempt to terminate P) or as is normally the case by Venus in its
276   In case P is woken up by a signal and not by Venus, it will first look
278   handle its signal without notifying Venus.  If Venus has READ, and
279   the request should not be processed, P can send Venus a signal message
281   signals are put in the queue at the head, and read first by Venus.  If
294   implementation of a character device associated with Coda.  Venus
313   This section describes the upcalls a Coda FS driver can make to Venus.
341   requested from Venus. There are approximately 30 upcalls at present
348   data structures shared by the kernel and Venus.
353 4.1.  Data structures shared by the kernel and Venus
373      It is questionable if we need CodaCreds in Venus. Finally Venus
397   The next important structure shared between Venus and the kernel is
492     This call is made to Venus during the initialization of
496     indicating the difficulty Venus encountered in locating the root of
528     and Venus will search the directory identified by cfs_lookup_in.VFid.
538   It is extremely important to realize that Venus bitwise ors the field
586      both at the Venus/kernel interaction level and at the RPC level.
624     be inaccessible, or permission may not be granted by Venus.
957     This request asks Venus to place the file identified by
1000      The flags argument is bogus and not used.  However, Venus' code
1002      be used to inform Venus that the file was closed but is still memory
1004      fetching the data in Venus vproc_vfscalls.  This seems silly.  If a
1007      currently Venus might think a file can be flushed from the cache when
1043     data arguments are filled as usual.  flags is not used by Venus.
1048      business about PREFETCHING in the Venus code?
1128     instructs Venus to do an FSDB->Get.
1149     This upcall asks Venus to do a get operation on an fsobj
1156      These can be "pinned" in the Venus cache using vget and released with
1165     Tell Venus to update the RVM attributes of a file.
1181     Ask Venus to update RVM attributes of object VFid. This
1193     Tell Venus a vnode is no longer in use.
1247     This upcall asks Venus to read or write from a file.
1253     read/write operations never reach Venus.  I have been told the
1283     Asks Venus to return the rootfid of a Coda system named
1290      It is not used by Coda proper.  Call is not implemented by Venus.
1311   .. Note:: Gut it. Call is not implemented by Venus.
1330   .. Note:: Gut it. Call is not implemented by Venus.
1351     Venus worker.cc has support for this call, although it is
1365     Send Venus a signal about an upcall.
1377     This is an out-of-band upcall to Venus to inform Venus
1378     that the calling process received a signal after Venus read the
1379     message from the input queue.  Venus is supposed to clean up the
1387      We need to better understand what Venus needs to clean up and if
1390      what state changes in Venus take place after an upcall for which the
1391      kernel is responsible for notifying Venus to clean up (e.g. open
1402   information is that Venus will notify the FS Driver that cached
1407   FileHandles in Windows) with the ViceFid's which Venus maintains.  The
1429   When Venus obtains information that indicates that cache entries are
1455     Venus issues this call upon startup and when it dies. This
1468 	  struct cfs_purgeuser_out {/* CFS_PURGEUSER is a venus->kernel call */
1486 	  struct cfs_zapfile_out {  /* CFS_ZAPFILE is a venus->kernel call */
1512 	  struct cfs_zapdir_out {   /* CFS_ZAPDIR is a venus->kernel call */
1521     Venus receives a callback on the directory.
1532 	  struct cfs_zapvnode_out { /* CFS_ZAPVNODE is a venus->kernel call */
1551 	  struct cfs_purgefid_out { /* CFS_PURGEFID is a venus->kernel call */
1574 	  struct cfs_replace_out { /* cfs_replace is a venus->kernel call */
1583     another.  It is added to allow Venus during reintegration to replace
1593   FS Driver at startup and upon shutdown or Venus failures.  Before
1658   8. Mounting the Coda filesystem should fail gracefully if Venus cannot
1660      best implemented by Venus fetching these objects before attempting