1f476c6edSMauro Carvalho Chehab.. SPDX-License-Identifier: GPL-2.0 2f476c6edSMauro Carvalho Chehab 3f476c6edSMauro Carvalho Chehab=========================== 4f476c6edSMauro Carvalho ChehabCoda Kernel-Venus Interface 5f476c6edSMauro Carvalho Chehab=========================== 6f476c6edSMauro Carvalho Chehab 7f476c6edSMauro Carvalho Chehab.. Note:: 8f476c6edSMauro Carvalho Chehab 9f476c6edSMauro Carvalho Chehab This is one of the technical documents describing a component of 10f476c6edSMauro Carvalho Chehab Coda -- this document describes the client kernel-Venus interface. 11f476c6edSMauro Carvalho Chehab 12f476c6edSMauro Carvalho ChehabFor more information: 13f476c6edSMauro Carvalho Chehab 14f476c6edSMauro Carvalho Chehab http://www.coda.cs.cmu.edu 15f476c6edSMauro Carvalho Chehab 16f476c6edSMauro Carvalho ChehabFor user level software needed to run Coda: 17f476c6edSMauro Carvalho Chehab 18f476c6edSMauro Carvalho Chehab ftp://ftp.coda.cs.cmu.edu 19f476c6edSMauro Carvalho Chehab 20f476c6edSMauro Carvalho ChehabTo run Coda you need to get a user level cache manager for the client, 21f476c6edSMauro Carvalho Chehabnamed Venus, as well as tools to manipulate ACLs, to log in, etc. The 22f476c6edSMauro Carvalho Chehabclient needs to have the Coda filesystem selected in the kernel 23f476c6edSMauro Carvalho Chehabconfiguration. 24f476c6edSMauro Carvalho Chehab 25f476c6edSMauro Carvalho ChehabThe server needs a user level server and at present does not depend on 26f476c6edSMauro Carvalho Chehabkernel support. 27f476c6edSMauro Carvalho Chehab 28f476c6edSMauro Carvalho Chehab The Venus kernel interface 29f476c6edSMauro Carvalho Chehab 30f476c6edSMauro Carvalho Chehab Peter J. Braam 31f476c6edSMauro Carvalho Chehab 32f476c6edSMauro Carvalho Chehab v1.0, Nov 9, 1997 33f476c6edSMauro Carvalho Chehab 34f476c6edSMauro Carvalho Chehab This document describes the communication between Venus and kernel 35f476c6edSMauro Carvalho Chehab level filesystem code needed for the operation of the Coda file sys- 36f476c6edSMauro Carvalho Chehab tem. This document version is meant to describe the current interface 37f476c6edSMauro Carvalho Chehab (version 1.0) as well as improvements we envisage. 38f476c6edSMauro Carvalho Chehab 39f476c6edSMauro Carvalho Chehab.. Table of Contents 40f476c6edSMauro Carvalho Chehab 41f476c6edSMauro Carvalho Chehab 1. Introduction 42f476c6edSMauro Carvalho Chehab 43f476c6edSMauro Carvalho Chehab 2. Servicing Coda filesystem calls 44f476c6edSMauro Carvalho Chehab 45f476c6edSMauro Carvalho Chehab 3. The message layer 46f476c6edSMauro Carvalho Chehab 47f476c6edSMauro Carvalho Chehab 3.1 Implementation details 48f476c6edSMauro Carvalho Chehab 49f476c6edSMauro Carvalho Chehab 4. The interface at the call level 50f476c6edSMauro Carvalho Chehab 51f476c6edSMauro Carvalho Chehab 4.1 Data structures shared by the kernel and Venus 52f476c6edSMauro Carvalho Chehab 4.2 The pioctl interface 53f476c6edSMauro Carvalho Chehab 4.3 root 54f476c6edSMauro Carvalho Chehab 4.4 lookup 55f476c6edSMauro Carvalho Chehab 4.5 getattr 56f476c6edSMauro Carvalho Chehab 4.6 setattr 57f476c6edSMauro Carvalho Chehab 4.7 access 58f476c6edSMauro Carvalho Chehab 4.8 create 59f476c6edSMauro Carvalho Chehab 4.9 mkdir 60f476c6edSMauro Carvalho Chehab 4.10 link 61f476c6edSMauro Carvalho Chehab 4.11 symlink 62f476c6edSMauro Carvalho Chehab 4.12 remove 63f476c6edSMauro Carvalho Chehab 4.13 rmdir 64f476c6edSMauro Carvalho Chehab 4.14 readlink 65f476c6edSMauro Carvalho Chehab 4.15 open 66f476c6edSMauro Carvalho Chehab 4.16 close 67f476c6edSMauro Carvalho Chehab 4.17 ioctl 68f476c6edSMauro Carvalho Chehab 4.18 rename 69f476c6edSMauro Carvalho Chehab 4.19 readdir 70f476c6edSMauro Carvalho Chehab 4.20 vget 71f476c6edSMauro Carvalho Chehab 4.21 fsync 72f476c6edSMauro Carvalho Chehab 4.22 inactive 73f476c6edSMauro Carvalho Chehab 4.23 rdwr 74f476c6edSMauro Carvalho Chehab 4.24 odymount 75f476c6edSMauro Carvalho Chehab 4.25 ody_lookup 76f476c6edSMauro Carvalho Chehab 4.26 ody_expand 77f476c6edSMauro Carvalho Chehab 4.27 prefetch 78f476c6edSMauro Carvalho Chehab 4.28 signal 79f476c6edSMauro Carvalho Chehab 80f476c6edSMauro Carvalho Chehab 5. The minicache and downcalls 81f476c6edSMauro Carvalho Chehab 82f476c6edSMauro Carvalho Chehab 5.1 INVALIDATE 83f476c6edSMauro Carvalho Chehab 5.2 FLUSH 84f476c6edSMauro Carvalho Chehab 5.3 PURGEUSER 85f476c6edSMauro Carvalho Chehab 5.4 ZAPFILE 86f476c6edSMauro Carvalho Chehab 5.5 ZAPDIR 87f476c6edSMauro Carvalho Chehab 5.6 ZAPVNODE 88f476c6edSMauro Carvalho Chehab 5.7 PURGEFID 89f476c6edSMauro Carvalho Chehab 5.8 REPLACE 90f476c6edSMauro Carvalho Chehab 91f476c6edSMauro Carvalho Chehab 6. Initialization and cleanup 92f476c6edSMauro Carvalho Chehab 93f476c6edSMauro Carvalho Chehab 6.1 Requirements 94f476c6edSMauro Carvalho Chehab 95f476c6edSMauro Carvalho Chehab1. Introduction 96f476c6edSMauro Carvalho Chehab=============== 97f476c6edSMauro Carvalho Chehab 98f476c6edSMauro Carvalho Chehab A key component in the Coda Distributed File System is the cache 99f476c6edSMauro Carvalho Chehab manager, Venus. 100f476c6edSMauro Carvalho Chehab 101f476c6edSMauro Carvalho Chehab When processes on a Coda enabled system access files in the Coda 102f476c6edSMauro Carvalho Chehab filesystem, requests are directed at the filesystem layer in the 103f476c6edSMauro Carvalho Chehab operating system. The operating system will communicate with Venus to 104f476c6edSMauro Carvalho Chehab service the request for the process. Venus manages a persistent 105f476c6edSMauro Carvalho Chehab client cache and makes remote procedure calls to Coda file servers and 106f476c6edSMauro Carvalho Chehab related servers (such as authentication servers) to service these 107f476c6edSMauro Carvalho Chehab requests it receives from the operating system. When Venus has 108f476c6edSMauro Carvalho Chehab serviced a request it replies to the operating system with appropriate 109f476c6edSMauro Carvalho Chehab return codes, and other data related to the request. Optionally the 110f476c6edSMauro Carvalho Chehab kernel support for Coda may maintain a minicache of recently processed 111f476c6edSMauro Carvalho Chehab requests to limit the number of interactions with Venus. Venus 112f476c6edSMauro Carvalho Chehab possesses the facility to inform the kernel when elements from its 113f476c6edSMauro Carvalho Chehab minicache are no longer valid. 114f476c6edSMauro Carvalho Chehab 115f476c6edSMauro Carvalho Chehab This document describes precisely this communication between the 116f476c6edSMauro Carvalho Chehab kernel and Venus. The definitions of so called upcalls and downcalls 117f476c6edSMauro Carvalho Chehab will be given with the format of the data they handle. We shall also 118f476c6edSMauro Carvalho Chehab describe the semantic invariants resulting from the calls. 119f476c6edSMauro Carvalho Chehab 120f476c6edSMauro Carvalho Chehab Historically Coda was implemented in a BSD file system in Mach 2.6. 121f476c6edSMauro Carvalho Chehab The interface between the kernel and Venus is very similar to the BSD 122f476c6edSMauro Carvalho Chehab VFS interface. Similar functionality is provided, and the format of 123f476c6edSMauro Carvalho Chehab the parameters and returned data is very similar to the BSD VFS. This 124f476c6edSMauro Carvalho Chehab leads to an almost natural environment for implementing a kernel-level 125f476c6edSMauro Carvalho Chehab filesystem driver for Coda in a BSD system. However, other operating 126f476c6edSMauro Carvalho Chehab systems such as Linux and Windows 95 and NT have virtual filesystem 127f476c6edSMauro Carvalho Chehab with different interfaces. 128f476c6edSMauro Carvalho Chehab 129f476c6edSMauro Carvalho Chehab To implement Coda on these systems some reverse engineering of the 130f476c6edSMauro Carvalho Chehab Venus/Kernel protocol is necessary. Also it came to light that other 131f476c6edSMauro Carvalho Chehab systems could profit significantly from certain small optimizations 132f476c6edSMauro Carvalho Chehab and modifications to the protocol. To facilitate this work as well as 133f476c6edSMauro Carvalho Chehab to make future ports easier, communication between Venus and the 134f476c6edSMauro Carvalho Chehab kernel should be documented in great detail. This is the aim of this 135f476c6edSMauro Carvalho Chehab document. 136f476c6edSMauro Carvalho Chehab 137f476c6edSMauro Carvalho Chehab2. Servicing Coda filesystem calls 138f476c6edSMauro Carvalho Chehab=================================== 139f476c6edSMauro Carvalho Chehab 140f476c6edSMauro Carvalho Chehab The service of a request for a Coda file system service originates in 141f476c6edSMauro Carvalho Chehab a process P which accessing a Coda file. It makes a system call which 142f476c6edSMauro Carvalho Chehab traps to the OS kernel. Examples of such calls trapping to the kernel 143f476c6edSMauro Carvalho Chehab are ``read``, ``write``, ``open``, ``close``, ``create``, ``mkdir``, 144f476c6edSMauro Carvalho Chehab ``rmdir``, ``chmod`` in a Unix ontext. Similar calls exist in the Win32 145f476c6edSMauro Carvalho Chehab environment, and are named ``CreateFile``. 146f476c6edSMauro Carvalho Chehab 147f476c6edSMauro Carvalho Chehab Generally the operating system handles the request in a virtual 148f476c6edSMauro Carvalho Chehab filesystem (VFS) layer, which is named I/O Manager in NT and IFS 149f476c6edSMauro Carvalho Chehab manager in Windows 95. The VFS is responsible for partial processing 150f476c6edSMauro Carvalho Chehab of the request and for locating the specific filesystem(s) which will 151f476c6edSMauro Carvalho Chehab service parts of the request. Usually the information in the path 152f476c6edSMauro Carvalho Chehab assists in locating the correct FS drivers. Sometimes after extensive 153f476c6edSMauro Carvalho Chehab pre-processing, the VFS starts invoking exported routines in the FS 154f476c6edSMauro Carvalho Chehab driver. This is the point where the FS specific processing of the 155f476c6edSMauro Carvalho Chehab request starts, and here the Coda specific kernel code comes into 156f476c6edSMauro Carvalho Chehab play. 157f476c6edSMauro Carvalho Chehab 158f476c6edSMauro Carvalho Chehab The FS layer for Coda must expose and implement several interfaces. 159f476c6edSMauro Carvalho Chehab First and foremost the VFS must be able to make all necessary calls to 160f476c6edSMauro Carvalho Chehab the Coda FS layer, so the Coda FS driver must expose the VFS interface 161f476c6edSMauro Carvalho Chehab as applicable in the operating system. These differ very significantly 162f476c6edSMauro Carvalho Chehab among operating systems, but share features such as facilities to 163f476c6edSMauro Carvalho Chehab read/write and create and remove objects. The Coda FS layer services 164f476c6edSMauro Carvalho Chehab such VFS requests by invoking one or more well defined services 165f476c6edSMauro Carvalho Chehab offered by the cache manager Venus. When the replies from Venus have 166f476c6edSMauro Carvalho Chehab come back to the FS driver, servicing of the VFS call continues and 167f476c6edSMauro Carvalho Chehab finishes with a reply to the kernel's VFS. Finally the VFS layer 168f476c6edSMauro Carvalho Chehab returns to the process. 169f476c6edSMauro Carvalho Chehab 170f476c6edSMauro Carvalho Chehab As a result of this design a basic interface exposed by the FS driver 171f476c6edSMauro Carvalho Chehab must allow Venus to manage message traffic. In particular Venus must 172f476c6edSMauro Carvalho Chehab be able to retrieve and place messages and to be notified of the 173f476c6edSMauro Carvalho Chehab arrival of a new message. The notification must be through a mechanism 174f476c6edSMauro Carvalho Chehab which does not block Venus since Venus must attend to other tasks even 175f476c6edSMauro Carvalho Chehab when no messages are waiting or being processed. 176f476c6edSMauro Carvalho Chehab 177f476c6edSMauro Carvalho Chehab **Interfaces of the Coda FS Driver** 178f476c6edSMauro Carvalho Chehab 179f476c6edSMauro Carvalho Chehab Furthermore the FS layer provides for a special path of communication 180f476c6edSMauro Carvalho Chehab between a user process and Venus, called the pioctl interface. The 181f476c6edSMauro Carvalho Chehab pioctl interface is used for Coda specific services, such as 182f476c6edSMauro Carvalho Chehab requesting detailed information about the persistent cache managed by 183f476c6edSMauro Carvalho Chehab Venus. Here the involvement of the kernel is minimal. It identifies 184f476c6edSMauro Carvalho Chehab the calling process and passes the information on to Venus. When 185f476c6edSMauro Carvalho Chehab Venus replies the response is passed back to the caller in unmodified 186f476c6edSMauro Carvalho Chehab form. 187f476c6edSMauro Carvalho Chehab 188f476c6edSMauro Carvalho Chehab Finally Venus allows the kernel FS driver to cache the results from 189f476c6edSMauro Carvalho Chehab certain services. This is done to avoid excessive context switches 190f476c6edSMauro Carvalho Chehab and results in an efficient system. However, Venus may acquire 191f476c6edSMauro Carvalho Chehab information, for example from the network which implies that cached 192f476c6edSMauro Carvalho Chehab information must be flushed or replaced. Venus then makes a downcall 193f476c6edSMauro Carvalho Chehab to the Coda FS layer to request flushes or updates in the cache. The 194f476c6edSMauro Carvalho Chehab kernel FS driver handles such requests synchronously. 195f476c6edSMauro Carvalho Chehab 196f476c6edSMauro Carvalho Chehab Among these interfaces the VFS interface and the facility to place, 197f476c6edSMauro Carvalho Chehab receive and be notified of messages are platform specific. We will 198f476c6edSMauro Carvalho Chehab not go into the calls exported to the VFS layer but we will state the 199f476c6edSMauro Carvalho Chehab requirements of the message exchange mechanism. 200f476c6edSMauro Carvalho Chehab 201f476c6edSMauro Carvalho Chehab 202f476c6edSMauro Carvalho Chehab3. The message layer 203f476c6edSMauro Carvalho Chehab===================== 204f476c6edSMauro Carvalho Chehab 205f476c6edSMauro Carvalho Chehab At the lowest level the communication between Venus and the FS driver 206f476c6edSMauro Carvalho Chehab proceeds through messages. The synchronization between processes 207f476c6edSMauro Carvalho Chehab requesting Coda file service and Venus relies on blocking and waking 208f476c6edSMauro Carvalho Chehab up processes. The Coda FS driver processes VFS- and pioctl-requests 209f476c6edSMauro Carvalho Chehab on behalf of a process P, creates messages for Venus, awaits replies 210f476c6edSMauro Carvalho Chehab and finally returns to the caller. The implementation of the exchange 211f476c6edSMauro Carvalho Chehab of messages is platform specific, but the semantics have (so far) 212f476c6edSMauro Carvalho Chehab appeared to be generally applicable. Data buffers are created by the 213f476c6edSMauro Carvalho Chehab FS Driver in kernel memory on behalf of P and copied to user memory in 214f476c6edSMauro Carvalho Chehab Venus. 215f476c6edSMauro Carvalho Chehab 216f476c6edSMauro Carvalho Chehab The FS Driver while servicing P makes upcalls to Venus. Such an 217f476c6edSMauro Carvalho Chehab upcall is dispatched to Venus by creating a message structure. The 218f476c6edSMauro Carvalho Chehab structure contains the identification of P, the message sequence 219f476c6edSMauro Carvalho Chehab number, the size of the request and a pointer to the data in kernel 220f476c6edSMauro Carvalho Chehab memory for the request. Since the data buffer is re-used to hold the 221f476c6edSMauro Carvalho Chehab reply from Venus, there is a field for the size of the reply. A flags 222f476c6edSMauro Carvalho Chehab field is used in the message to precisely record the status of the 223f476c6edSMauro Carvalho Chehab message. Additional platform dependent structures involve pointers to 224f476c6edSMauro Carvalho Chehab determine the position of the message on queues and pointers to 225f476c6edSMauro Carvalho Chehab synchronization objects. In the upcall routine the message structure 226f476c6edSMauro Carvalho Chehab is filled in, flags are set to 0, and it is placed on the *pending* 227f476c6edSMauro Carvalho Chehab queue. The routine calling upcall is responsible for allocating the 228f476c6edSMauro Carvalho Chehab data buffer; its structure will be described in the next section. 229f476c6edSMauro Carvalho Chehab 230f476c6edSMauro Carvalho Chehab A facility must exist to notify Venus that the message has been 231f476c6edSMauro Carvalho Chehab created, and implemented using available synchronization objects in 232f476c6edSMauro Carvalho Chehab the OS. This notification is done in the upcall context of the process 233f476c6edSMauro Carvalho Chehab P. When the message is on the pending queue, process P cannot proceed 234f476c6edSMauro Carvalho Chehab in upcall. The (kernel mode) processing of P in the filesystem 235f476c6edSMauro Carvalho Chehab request routine must be suspended until Venus has replied. Therefore 236f476c6edSMauro Carvalho Chehab the calling thread in P is blocked in upcall. A pointer in the 237f476c6edSMauro Carvalho Chehab message structure will locate the synchronization object on which P is 238f476c6edSMauro Carvalho Chehab sleeping. 239f476c6edSMauro Carvalho Chehab 240f476c6edSMauro Carvalho Chehab Venus detects the notification that a message has arrived, and the FS 241f476c6edSMauro Carvalho Chehab driver allow Venus to retrieve the message with a getmsg_from_kernel 242f476c6edSMauro Carvalho Chehab call. This action finishes in the kernel by putting the message on the 243f476c6edSMauro Carvalho Chehab queue of processing messages and setting flags to READ. Venus is 244f476c6edSMauro Carvalho Chehab passed the contents of the data buffer. The getmsg_from_kernel call 245f476c6edSMauro Carvalho Chehab now returns and Venus processes the request. 246f476c6edSMauro Carvalho Chehab 247f476c6edSMauro Carvalho Chehab At some later point the FS driver receives a message from Venus, 248f476c6edSMauro Carvalho Chehab namely when Venus calls sendmsg_to_kernel. At this moment the Coda FS 249f476c6edSMauro Carvalho Chehab driver looks at the contents of the message and decides if: 250f476c6edSMauro Carvalho Chehab 251f476c6edSMauro Carvalho Chehab 252f476c6edSMauro Carvalho Chehab * the message is a reply for a suspended thread P. If so it removes 253f476c6edSMauro Carvalho Chehab the message from the processing queue and marks the message as 254f476c6edSMauro Carvalho Chehab WRITTEN. Finally, the FS driver unblocks P (still in the kernel 255f476c6edSMauro Carvalho Chehab mode context of Venus) and the sendmsg_to_kernel call returns to 256f476c6edSMauro Carvalho Chehab Venus. The process P will be scheduled at some point and continues 257f476c6edSMauro Carvalho Chehab processing its upcall with the data buffer replaced with the reply 258f476c6edSMauro Carvalho Chehab from Venus. 259f476c6edSMauro Carvalho Chehab 260f476c6edSMauro Carvalho Chehab * The message is a ``downcall``. A downcall is a request from Venus to 261f476c6edSMauro Carvalho Chehab the FS Driver. The FS driver processes the request immediately 262f476c6edSMauro Carvalho Chehab (usually a cache eviction or replacement) and when it finishes 263f476c6edSMauro Carvalho Chehab sendmsg_to_kernel returns. 264f476c6edSMauro Carvalho Chehab 265f476c6edSMauro Carvalho Chehab Now P awakes and continues processing upcall. There are some 266f476c6edSMauro Carvalho Chehab subtleties to take account of. First P will determine if it was woken 267f476c6edSMauro Carvalho Chehab up in upcall by a signal from some other source (for example an 268f476c6edSMauro Carvalho Chehab attempt to terminate P) or as is normally the case by Venus in its 269f476c6edSMauro Carvalho Chehab sendmsg_to_kernel call. In the normal case, the upcall routine will 270f476c6edSMauro Carvalho Chehab deallocate the message structure and return. The FS routine can proceed 271f476c6edSMauro Carvalho Chehab with its processing. 272f476c6edSMauro Carvalho Chehab 273f476c6edSMauro Carvalho Chehab 274f476c6edSMauro Carvalho Chehab **Sleeping and IPC arrangements** 275f476c6edSMauro Carvalho Chehab 276f476c6edSMauro Carvalho Chehab In case P is woken up by a signal and not by Venus, it will first look 277f476c6edSMauro Carvalho Chehab at the flags field. If the message is not yet READ, the process P can 278f476c6edSMauro Carvalho Chehab handle its signal without notifying Venus. If Venus has READ, and 279f476c6edSMauro Carvalho Chehab the request should not be processed, P can send Venus a signal message 280f476c6edSMauro Carvalho Chehab to indicate that it should disregard the previous message. Such 281f476c6edSMauro Carvalho Chehab signals are put in the queue at the head, and read first by Venus. If 282f476c6edSMauro Carvalho Chehab the message is already marked as WRITTEN it is too late to stop the 283f476c6edSMauro Carvalho Chehab processing. The VFS routine will now continue. (-- If a VFS request 284f476c6edSMauro Carvalho Chehab involves more than one upcall, this can lead to complicated state, an 285f476c6edSMauro Carvalho Chehab extra field "handle_signals" could be added in the message structure 286f476c6edSMauro Carvalho Chehab to indicate points of no return have been passed.--) 287f476c6edSMauro Carvalho Chehab 288f476c6edSMauro Carvalho Chehab 289f476c6edSMauro Carvalho Chehab 290f476c6edSMauro Carvalho Chehab3.1. Implementation details 291f476c6edSMauro Carvalho Chehab---------------------------- 292f476c6edSMauro Carvalho Chehab 293f476c6edSMauro Carvalho Chehab The Unix implementation of this mechanism has been through the 294f476c6edSMauro Carvalho Chehab implementation of a character device associated with Coda. Venus 295f476c6edSMauro Carvalho Chehab retrieves messages by doing a read on the device, replies are sent 296f476c6edSMauro Carvalho Chehab with a write and notification is through the select system call on the 297f476c6edSMauro Carvalho Chehab file descriptor for the device. The process P is kept waiting on an 298f476c6edSMauro Carvalho Chehab interruptible wait queue object. 299f476c6edSMauro Carvalho Chehab 300f476c6edSMauro Carvalho Chehab In Windows NT and the DPMI Windows 95 implementation a DeviceIoControl 301f476c6edSMauro Carvalho Chehab call is used. The DeviceIoControl call is designed to copy buffers 302f476c6edSMauro Carvalho Chehab from user memory to kernel memory with OPCODES. The sendmsg_to_kernel 303f476c6edSMauro Carvalho Chehab is issued as a synchronous call, while the getmsg_from_kernel call is 304f476c6edSMauro Carvalho Chehab asynchronous. Windows EventObjects are used for notification of 305f476c6edSMauro Carvalho Chehab message arrival. The process P is kept waiting on a KernelEvent 306f476c6edSMauro Carvalho Chehab object in NT and a semaphore in Windows 95. 307f476c6edSMauro Carvalho Chehab 308f476c6edSMauro Carvalho Chehab 309f476c6edSMauro Carvalho Chehab4. The interface at the call level 310f476c6edSMauro Carvalho Chehab=================================== 311f476c6edSMauro Carvalho Chehab 312f476c6edSMauro Carvalho Chehab 313f476c6edSMauro Carvalho Chehab This section describes the upcalls a Coda FS driver can make to Venus. 314f476c6edSMauro Carvalho Chehab Each of these upcalls make use of two structures: inputArgs and 315f476c6edSMauro Carvalho Chehab outputArgs. In pseudo BNF form the structures take the following 316f476c6edSMauro Carvalho Chehab form:: 317f476c6edSMauro Carvalho Chehab 318f476c6edSMauro Carvalho Chehab 319f476c6edSMauro Carvalho Chehab struct inputArgs { 320f476c6edSMauro Carvalho Chehab u_long opcode; 321f476c6edSMauro Carvalho Chehab u_long unique; /* Keep multiple outstanding msgs distinct */ 322f476c6edSMauro Carvalho Chehab u_short pid; /* Common to all */ 323f476c6edSMauro Carvalho Chehab u_short pgid; /* Common to all */ 324f476c6edSMauro Carvalho Chehab struct CodaCred cred; /* Common to all */ 325f476c6edSMauro Carvalho Chehab 326f476c6edSMauro Carvalho Chehab <union "in" of call dependent parts of inputArgs> 327f476c6edSMauro Carvalho Chehab }; 328f476c6edSMauro Carvalho Chehab 329f476c6edSMauro Carvalho Chehab struct outputArgs { 330f476c6edSMauro Carvalho Chehab u_long opcode; 331f476c6edSMauro Carvalho Chehab u_long unique; /* Keep multiple outstanding msgs distinct */ 332f476c6edSMauro Carvalho Chehab u_long result; 333f476c6edSMauro Carvalho Chehab 334f476c6edSMauro Carvalho Chehab <union "out" of call dependent parts of inputArgs> 335f476c6edSMauro Carvalho Chehab }; 336f476c6edSMauro Carvalho Chehab 337f476c6edSMauro Carvalho Chehab 338f476c6edSMauro Carvalho Chehab 339f476c6edSMauro Carvalho Chehab Before going on let us elucidate the role of the various fields. The 340f476c6edSMauro Carvalho Chehab inputArgs start with the opcode which defines the type of service 341f476c6edSMauro Carvalho Chehab requested from Venus. There are approximately 30 upcalls at present 342f476c6edSMauro Carvalho Chehab which we will discuss. The unique field labels the inputArg with a 343f476c6edSMauro Carvalho Chehab unique number which will identify the message uniquely. A process and 344f476c6edSMauro Carvalho Chehab process group id are passed. Finally the credentials of the caller 345f476c6edSMauro Carvalho Chehab are included. 346f476c6edSMauro Carvalho Chehab 347f476c6edSMauro Carvalho Chehab Before delving into the specific calls we need to discuss a variety of 348f476c6edSMauro Carvalho Chehab data structures shared by the kernel and Venus. 349f476c6edSMauro Carvalho Chehab 350f476c6edSMauro Carvalho Chehab 351f476c6edSMauro Carvalho Chehab 352f476c6edSMauro Carvalho Chehab 353f476c6edSMauro Carvalho Chehab4.1. Data structures shared by the kernel and Venus 354f476c6edSMauro Carvalho Chehab---------------------------------------------------- 355f476c6edSMauro Carvalho Chehab 356f476c6edSMauro Carvalho Chehab 357f476c6edSMauro Carvalho Chehab The CodaCred structure defines a variety of user and group ids as 358f476c6edSMauro Carvalho Chehab they are set for the calling process. The vuid_t and vgid_t are 32 bit 359f476c6edSMauro Carvalho Chehab unsigned integers. It also defines group membership in an array. On 360f476c6edSMauro Carvalho Chehab Unix the CodaCred has proven sufficient to implement good security 361f476c6edSMauro Carvalho Chehab semantics for Coda but the structure may have to undergo modification 362f476c6edSMauro Carvalho Chehab for the Windows environment when these mature:: 363f476c6edSMauro Carvalho Chehab 364f476c6edSMauro Carvalho Chehab struct CodaCred { 365f476c6edSMauro Carvalho Chehab vuid_t cr_uid, cr_euid, cr_suid, cr_fsuid; /* Real, effective, set, fs uid */ 366f476c6edSMauro Carvalho Chehab vgid_t cr_gid, cr_egid, cr_sgid, cr_fsgid; /* same for groups */ 367f476c6edSMauro Carvalho Chehab vgid_t cr_groups[NGROUPS]; /* Group membership for caller */ 368f476c6edSMauro Carvalho Chehab }; 369f476c6edSMauro Carvalho Chehab 370f476c6edSMauro Carvalho Chehab 371f476c6edSMauro Carvalho Chehab .. Note:: 372f476c6edSMauro Carvalho Chehab 373f476c6edSMauro Carvalho Chehab It is questionable if we need CodaCreds in Venus. Finally Venus 374f476c6edSMauro Carvalho Chehab doesn't know about groups, although it does create files with the 375f476c6edSMauro Carvalho Chehab default uid/gid. Perhaps the list of group membership is superfluous. 376f476c6edSMauro Carvalho Chehab 377f476c6edSMauro Carvalho Chehab 378f476c6edSMauro Carvalho Chehab The next item is the fundamental identifier used to identify Coda 379f476c6edSMauro Carvalho Chehab files, the ViceFid. A fid of a file uniquely defines a file or 380f476c6edSMauro Carvalho Chehab directory in the Coda filesystem within a cell [1]_:: 381f476c6edSMauro Carvalho Chehab 382f476c6edSMauro Carvalho Chehab typedef struct ViceFid { 383f476c6edSMauro Carvalho Chehab VolumeId Volume; 384f476c6edSMauro Carvalho Chehab VnodeId Vnode; 385f476c6edSMauro Carvalho Chehab Unique_t Unique; 386f476c6edSMauro Carvalho Chehab } ViceFid; 387f476c6edSMauro Carvalho Chehab 388f476c6edSMauro Carvalho Chehab .. [1] A cell is agroup of Coda servers acting under the aegis of a single 389f476c6edSMauro Carvalho Chehab system control machine or SCM. See the Coda Administration manual 390f476c6edSMauro Carvalho Chehab for a detailed description of the role of the SCM. 391f476c6edSMauro Carvalho Chehab 392f476c6edSMauro Carvalho Chehab Each of the constituent fields: VolumeId, VnodeId and Unique_t are 393f476c6edSMauro Carvalho Chehab unsigned 32 bit integers. We envisage that a further field will need 394f476c6edSMauro Carvalho Chehab to be prefixed to identify the Coda cell; this will probably take the 395f476c6edSMauro Carvalho Chehab form of a Ipv6 size IP address naming the Coda cell through DNS. 396f476c6edSMauro Carvalho Chehab 397f476c6edSMauro Carvalho Chehab The next important structure shared between Venus and the kernel is 398f476c6edSMauro Carvalho Chehab the attributes of the file. The following structure is used to 399f476c6edSMauro Carvalho Chehab exchange information. It has room for future extensions such as 400f476c6edSMauro Carvalho Chehab support for device files (currently not present in Coda):: 401f476c6edSMauro Carvalho Chehab 402f476c6edSMauro Carvalho Chehab 403f476c6edSMauro Carvalho Chehab struct coda_timespec { 404f476c6edSMauro Carvalho Chehab int64_t tv_sec; /* seconds */ 405f476c6edSMauro Carvalho Chehab long tv_nsec; /* nanoseconds */ 406f476c6edSMauro Carvalho Chehab }; 407f476c6edSMauro Carvalho Chehab 408f476c6edSMauro Carvalho Chehab struct coda_vattr { 409f476c6edSMauro Carvalho Chehab enum coda_vtype va_type; /* vnode type (for create) */ 410f476c6edSMauro Carvalho Chehab u_short va_mode; /* files access mode and type */ 411f476c6edSMauro Carvalho Chehab short va_nlink; /* number of references to file */ 412f476c6edSMauro Carvalho Chehab vuid_t va_uid; /* owner user id */ 413f476c6edSMauro Carvalho Chehab vgid_t va_gid; /* owner group id */ 414f476c6edSMauro Carvalho Chehab long va_fsid; /* file system id (dev for now) */ 415f476c6edSMauro Carvalho Chehab long va_fileid; /* file id */ 416f476c6edSMauro Carvalho Chehab u_quad_t va_size; /* file size in bytes */ 417f476c6edSMauro Carvalho Chehab long va_blocksize; /* blocksize preferred for i/o */ 418f476c6edSMauro Carvalho Chehab struct coda_timespec va_atime; /* time of last access */ 419f476c6edSMauro Carvalho Chehab struct coda_timespec va_mtime; /* time of last modification */ 420f476c6edSMauro Carvalho Chehab struct coda_timespec va_ctime; /* time file changed */ 421f476c6edSMauro Carvalho Chehab u_long va_gen; /* generation number of file */ 422f476c6edSMauro Carvalho Chehab u_long va_flags; /* flags defined for file */ 423f476c6edSMauro Carvalho Chehab dev_t va_rdev; /* device special file represents */ 424f476c6edSMauro Carvalho Chehab u_quad_t va_bytes; /* bytes of disk space held by file */ 425f476c6edSMauro Carvalho Chehab u_quad_t va_filerev; /* file modification number */ 426f476c6edSMauro Carvalho Chehab u_int va_vaflags; /* operations flags, see below */ 427f476c6edSMauro Carvalho Chehab long va_spare; /* remain quad aligned */ 428f476c6edSMauro Carvalho Chehab }; 429f476c6edSMauro Carvalho Chehab 430f476c6edSMauro Carvalho Chehab 431f476c6edSMauro Carvalho Chehab4.2. The pioctl interface 432f476c6edSMauro Carvalho Chehab-------------------------- 433f476c6edSMauro Carvalho Chehab 434f476c6edSMauro Carvalho Chehab 435f476c6edSMauro Carvalho Chehab Coda specific requests can be made by application through the pioctl 436f476c6edSMauro Carvalho Chehab interface. The pioctl is implemented as an ordinary ioctl on a 437f476c6edSMauro Carvalho Chehab fictitious file /coda/.CONTROL. The pioctl call opens this file, gets 438f476c6edSMauro Carvalho Chehab a file handle and makes the ioctl call. Finally it closes the file. 439f476c6edSMauro Carvalho Chehab 440f476c6edSMauro Carvalho Chehab The kernel involvement in this is limited to providing the facility to 441f476c6edSMauro Carvalho Chehab open and close and pass the ioctl message and to verify that a path in 442f476c6edSMauro Carvalho Chehab the pioctl data buffers is a file in a Coda filesystem. 443f476c6edSMauro Carvalho Chehab 444f476c6edSMauro Carvalho Chehab The kernel is handed a data packet of the form:: 445f476c6edSMauro Carvalho Chehab 446f476c6edSMauro Carvalho Chehab struct { 447f476c6edSMauro Carvalho Chehab const char *path; 448f476c6edSMauro Carvalho Chehab struct ViceIoctl vidata; 449f476c6edSMauro Carvalho Chehab int follow; 450f476c6edSMauro Carvalho Chehab } data; 451f476c6edSMauro Carvalho Chehab 452f476c6edSMauro Carvalho Chehab 453f476c6edSMauro Carvalho Chehab 454f476c6edSMauro Carvalho Chehab where:: 455f476c6edSMauro Carvalho Chehab 456f476c6edSMauro Carvalho Chehab 457f476c6edSMauro Carvalho Chehab struct ViceIoctl { 458f476c6edSMauro Carvalho Chehab caddr_t in, out; /* Data to be transferred in, or out */ 459f476c6edSMauro Carvalho Chehab short in_size; /* Size of input buffer <= 2K */ 460f476c6edSMauro Carvalho Chehab short out_size; /* Maximum size of output buffer, <= 2K */ 461f476c6edSMauro Carvalho Chehab }; 462f476c6edSMauro Carvalho Chehab 463f476c6edSMauro Carvalho Chehab 464f476c6edSMauro Carvalho Chehab 465f476c6edSMauro Carvalho Chehab The path must be a Coda file, otherwise the ioctl upcall will not be 466f476c6edSMauro Carvalho Chehab made. 467f476c6edSMauro Carvalho Chehab 468f476c6edSMauro Carvalho Chehab .. Note:: The data structures and code are a mess. We need to clean this up. 469f476c6edSMauro Carvalho Chehab 470f476c6edSMauro Carvalho Chehab 471f476c6edSMauro Carvalho Chehab**We now proceed to document the individual calls**: 472f476c6edSMauro Carvalho Chehab 473f476c6edSMauro Carvalho Chehab 474f476c6edSMauro Carvalho Chehab4.3. root 475f476c6edSMauro Carvalho Chehab---------- 476f476c6edSMauro Carvalho Chehab 477f476c6edSMauro Carvalho Chehab 478f476c6edSMauro Carvalho Chehab Arguments 479f476c6edSMauro Carvalho Chehab in 480f476c6edSMauro Carvalho Chehab 481f476c6edSMauro Carvalho Chehab empty 482f476c6edSMauro Carvalho Chehab 483f476c6edSMauro Carvalho Chehab out:: 484f476c6edSMauro Carvalho Chehab 485f476c6edSMauro Carvalho Chehab struct cfs_root_out { 486f476c6edSMauro Carvalho Chehab ViceFid VFid; 487f476c6edSMauro Carvalho Chehab } cfs_root; 488f476c6edSMauro Carvalho Chehab 489f476c6edSMauro Carvalho Chehab 490f476c6edSMauro Carvalho Chehab 491f476c6edSMauro Carvalho Chehab Description 492f476c6edSMauro Carvalho Chehab This call is made to Venus during the initialization of 493f476c6edSMauro Carvalho Chehab the Coda filesystem. If the result is zero, the cfs_root structure 494f476c6edSMauro Carvalho Chehab contains the ViceFid of the root of the Coda filesystem. If a non-zero 495f476c6edSMauro Carvalho Chehab result is generated, its value is a platform dependent error code 496f476c6edSMauro Carvalho Chehab indicating the difficulty Venus encountered in locating the root of 497f476c6edSMauro Carvalho Chehab the Coda filesystem. 498f476c6edSMauro Carvalho Chehab 499f476c6edSMauro Carvalho Chehab4.4. lookup 500f476c6edSMauro Carvalho Chehab------------ 501f476c6edSMauro Carvalho Chehab 502f476c6edSMauro Carvalho Chehab 503f476c6edSMauro Carvalho Chehab Summary 504f476c6edSMauro Carvalho Chehab Find the ViceFid and type of an object in a directory if it exists. 505f476c6edSMauro Carvalho Chehab 506f476c6edSMauro Carvalho Chehab Arguments 507f476c6edSMauro Carvalho Chehab in:: 508f476c6edSMauro Carvalho Chehab 509f476c6edSMauro Carvalho Chehab struct cfs_lookup_in { 510f476c6edSMauro Carvalho Chehab ViceFid VFid; 511f476c6edSMauro Carvalho Chehab char *name; /* Place holder for data. */ 512f476c6edSMauro Carvalho Chehab } cfs_lookup; 513f476c6edSMauro Carvalho Chehab 514f476c6edSMauro Carvalho Chehab 515f476c6edSMauro Carvalho Chehab 516f476c6edSMauro Carvalho Chehab out:: 517f476c6edSMauro Carvalho Chehab 518f476c6edSMauro Carvalho Chehab struct cfs_lookup_out { 519f476c6edSMauro Carvalho Chehab ViceFid VFid; 520f476c6edSMauro Carvalho Chehab int vtype; 521f476c6edSMauro Carvalho Chehab } cfs_lookup; 522f476c6edSMauro Carvalho Chehab 523f476c6edSMauro Carvalho Chehab 524f476c6edSMauro Carvalho Chehab 525f476c6edSMauro Carvalho Chehab Description 526f476c6edSMauro Carvalho Chehab This call is made to determine the ViceFid and filetype of 5274b708d6eSRandy Dunlap a directory entry. The directory entry requested carries name 'name' 528f476c6edSMauro Carvalho Chehab and Venus will search the directory identified by cfs_lookup_in.VFid. 529f476c6edSMauro Carvalho Chehab The result may indicate that the name does not exist, or that 530f476c6edSMauro Carvalho Chehab difficulty was encountered in finding it (e.g. due to disconnection). 531f476c6edSMauro Carvalho Chehab If the result is zero, the field cfs_lookup_out.VFid contains the 532f476c6edSMauro Carvalho Chehab targets ViceFid and cfs_lookup_out.vtype the coda_vtype giving the 533f476c6edSMauro Carvalho Chehab type of object the name designates. 534f476c6edSMauro Carvalho Chehab 535f476c6edSMauro Carvalho Chehab The name of the object is an 8 bit character string of maximum length 536f476c6edSMauro Carvalho Chehab CFS_MAXNAMLEN, currently set to 256 (including a 0 terminator.) 537f476c6edSMauro Carvalho Chehab 538f476c6edSMauro Carvalho Chehab It is extremely important to realize that Venus bitwise ors the field 539f476c6edSMauro Carvalho Chehab cfs_lookup.vtype with CFS_NOCACHE to indicate that the object should 540f476c6edSMauro Carvalho Chehab not be put in the kernel name cache. 541f476c6edSMauro Carvalho Chehab 542f476c6edSMauro Carvalho Chehab .. Note:: 543f476c6edSMauro Carvalho Chehab 544f476c6edSMauro Carvalho Chehab The type of the vtype is currently wrong. It should be 545f476c6edSMauro Carvalho Chehab coda_vtype. Linux does not take note of CFS_NOCACHE. It should. 546f476c6edSMauro Carvalho Chehab 547f476c6edSMauro Carvalho Chehab 548f476c6edSMauro Carvalho Chehab4.5. getattr 549f476c6edSMauro Carvalho Chehab------------- 550f476c6edSMauro Carvalho Chehab 551f476c6edSMauro Carvalho Chehab 552f476c6edSMauro Carvalho Chehab Summary Get the attributes of a file. 553f476c6edSMauro Carvalho Chehab 554f476c6edSMauro Carvalho Chehab Arguments 555f476c6edSMauro Carvalho Chehab in:: 556f476c6edSMauro Carvalho Chehab 557f476c6edSMauro Carvalho Chehab struct cfs_getattr_in { 558f476c6edSMauro Carvalho Chehab ViceFid VFid; 559f476c6edSMauro Carvalho Chehab struct coda_vattr attr; /* XXXXX */ 560f476c6edSMauro Carvalho Chehab } cfs_getattr; 561f476c6edSMauro Carvalho Chehab 562f476c6edSMauro Carvalho Chehab 563f476c6edSMauro Carvalho Chehab 564f476c6edSMauro Carvalho Chehab out:: 565f476c6edSMauro Carvalho Chehab 566f476c6edSMauro Carvalho Chehab struct cfs_getattr_out { 567f476c6edSMauro Carvalho Chehab struct coda_vattr attr; 568f476c6edSMauro Carvalho Chehab } cfs_getattr; 569f476c6edSMauro Carvalho Chehab 570f476c6edSMauro Carvalho Chehab 571f476c6edSMauro Carvalho Chehab 572f476c6edSMauro Carvalho Chehab Description 573f476c6edSMauro Carvalho Chehab This call returns the attributes of the file identified by fid. 574f476c6edSMauro Carvalho Chehab 575f476c6edSMauro Carvalho Chehab Errors 576f476c6edSMauro Carvalho Chehab Errors can occur if the object with fid does not exist, is 577f476c6edSMauro Carvalho Chehab unaccessible or if the caller does not have permission to fetch 578f476c6edSMauro Carvalho Chehab attributes. 579f476c6edSMauro Carvalho Chehab 580f476c6edSMauro Carvalho Chehab .. Note:: 581f476c6edSMauro Carvalho Chehab 582f476c6edSMauro Carvalho Chehab Many kernel FS drivers (Linux, NT and Windows 95) need to acquire 583f476c6edSMauro Carvalho Chehab the attributes as well as the Fid for the instantiation of an internal 584f476c6edSMauro Carvalho Chehab "inode" or "FileHandle". A significant improvement in performance on 585f476c6edSMauro Carvalho Chehab such systems could be made by combining the lookup and getattr calls 586f476c6edSMauro Carvalho Chehab both at the Venus/kernel interaction level and at the RPC level. 587f476c6edSMauro Carvalho Chehab 588f476c6edSMauro Carvalho Chehab The vattr structure included in the input arguments is superfluous and 589f476c6edSMauro Carvalho Chehab should be removed. 590f476c6edSMauro Carvalho Chehab 591f476c6edSMauro Carvalho Chehab 592f476c6edSMauro Carvalho Chehab4.6. setattr 593f476c6edSMauro Carvalho Chehab------------- 594f476c6edSMauro Carvalho Chehab 595f476c6edSMauro Carvalho Chehab 596f476c6edSMauro Carvalho Chehab Summary 597f476c6edSMauro Carvalho Chehab Set the attributes of a file. 598f476c6edSMauro Carvalho Chehab 599f476c6edSMauro Carvalho Chehab Arguments 600f476c6edSMauro Carvalho Chehab in:: 601f476c6edSMauro Carvalho Chehab 602f476c6edSMauro Carvalho Chehab struct cfs_setattr_in { 603f476c6edSMauro Carvalho Chehab ViceFid VFid; 604f476c6edSMauro Carvalho Chehab struct coda_vattr attr; 605f476c6edSMauro Carvalho Chehab } cfs_setattr; 606f476c6edSMauro Carvalho Chehab 607f476c6edSMauro Carvalho Chehab 608f476c6edSMauro Carvalho Chehab 609f476c6edSMauro Carvalho Chehab 610f476c6edSMauro Carvalho Chehab out 611f476c6edSMauro Carvalho Chehab 612f476c6edSMauro Carvalho Chehab empty 613f476c6edSMauro Carvalho Chehab 614f476c6edSMauro Carvalho Chehab Description 615f476c6edSMauro Carvalho Chehab The structure attr is filled with attributes to be changed 616f476c6edSMauro Carvalho Chehab in BSD style. Attributes not to be changed are set to -1, apart from 617f476c6edSMauro Carvalho Chehab vtype which is set to VNON. Other are set to the value to be assigned. 618f476c6edSMauro Carvalho Chehab The only attributes which the FS driver may request to change are the 619f476c6edSMauro Carvalho Chehab mode, owner, groupid, atime, mtime and ctime. The return value 620f476c6edSMauro Carvalho Chehab indicates success or failure. 621f476c6edSMauro Carvalho Chehab 622f476c6edSMauro Carvalho Chehab Errors 623f476c6edSMauro Carvalho Chehab A variety of errors can occur. The object may not exist, may 624f476c6edSMauro Carvalho Chehab be inaccessible, or permission may not be granted by Venus. 625f476c6edSMauro Carvalho Chehab 626f476c6edSMauro Carvalho Chehab 627f476c6edSMauro Carvalho Chehab4.7. access 628f476c6edSMauro Carvalho Chehab------------ 629f476c6edSMauro Carvalho Chehab 630f476c6edSMauro Carvalho Chehab 631f476c6edSMauro Carvalho Chehab Arguments 632f476c6edSMauro Carvalho Chehab in:: 633f476c6edSMauro Carvalho Chehab 634f476c6edSMauro Carvalho Chehab struct cfs_access_in { 635f476c6edSMauro Carvalho Chehab ViceFid VFid; 636f476c6edSMauro Carvalho Chehab int flags; 637f476c6edSMauro Carvalho Chehab } cfs_access; 638f476c6edSMauro Carvalho Chehab 639f476c6edSMauro Carvalho Chehab 640f476c6edSMauro Carvalho Chehab 641f476c6edSMauro Carvalho Chehab out 642f476c6edSMauro Carvalho Chehab 643f476c6edSMauro Carvalho Chehab empty 644f476c6edSMauro Carvalho Chehab 645f476c6edSMauro Carvalho Chehab Description 646f476c6edSMauro Carvalho Chehab Verify if access to the object identified by VFid for 647f476c6edSMauro Carvalho Chehab operations described by flags is permitted. The result indicates if 648f476c6edSMauro Carvalho Chehab access will be granted. It is important to remember that Coda uses 649f476c6edSMauro Carvalho Chehab ACLs to enforce protection and that ultimately the servers, not the 650f476c6edSMauro Carvalho Chehab clients enforce the security of the system. The result of this call 651f476c6edSMauro Carvalho Chehab will depend on whether a token is held by the user. 652f476c6edSMauro Carvalho Chehab 653f476c6edSMauro Carvalho Chehab Errors 654f476c6edSMauro Carvalho Chehab The object may not exist, or the ACL describing the protection 655f476c6edSMauro Carvalho Chehab may not be accessible. 656f476c6edSMauro Carvalho Chehab 657f476c6edSMauro Carvalho Chehab 658f476c6edSMauro Carvalho Chehab4.8. create 659f476c6edSMauro Carvalho Chehab------------ 660f476c6edSMauro Carvalho Chehab 661f476c6edSMauro Carvalho Chehab 662f476c6edSMauro Carvalho Chehab Summary 663f476c6edSMauro Carvalho Chehab Invoked to create a file 664f476c6edSMauro Carvalho Chehab 665f476c6edSMauro Carvalho Chehab Arguments 666f476c6edSMauro Carvalho Chehab in:: 667f476c6edSMauro Carvalho Chehab 668f476c6edSMauro Carvalho Chehab struct cfs_create_in { 669f476c6edSMauro Carvalho Chehab ViceFid VFid; 670f476c6edSMauro Carvalho Chehab struct coda_vattr attr; 671f476c6edSMauro Carvalho Chehab int excl; 672f476c6edSMauro Carvalho Chehab int mode; 673f476c6edSMauro Carvalho Chehab char *name; /* Place holder for data. */ 674f476c6edSMauro Carvalho Chehab } cfs_create; 675f476c6edSMauro Carvalho Chehab 676f476c6edSMauro Carvalho Chehab 677f476c6edSMauro Carvalho Chehab 678f476c6edSMauro Carvalho Chehab 679f476c6edSMauro Carvalho Chehab out:: 680f476c6edSMauro Carvalho Chehab 681f476c6edSMauro Carvalho Chehab struct cfs_create_out { 682f476c6edSMauro Carvalho Chehab ViceFid VFid; 683f476c6edSMauro Carvalho Chehab struct coda_vattr attr; 684f476c6edSMauro Carvalho Chehab } cfs_create; 685f476c6edSMauro Carvalho Chehab 686f476c6edSMauro Carvalho Chehab 687f476c6edSMauro Carvalho Chehab 688f476c6edSMauro Carvalho Chehab Description 689f476c6edSMauro Carvalho Chehab This upcall is invoked to request creation of a file. 690f476c6edSMauro Carvalho Chehab The file will be created in the directory identified by VFid, its name 691f476c6edSMauro Carvalho Chehab will be name, and the mode will be mode. If excl is set an error will 692f476c6edSMauro Carvalho Chehab be returned if the file already exists. If the size field in attr is 693f476c6edSMauro Carvalho Chehab set to zero the file will be truncated. The uid and gid of the file 694f476c6edSMauro Carvalho Chehab are set by converting the CodaCred to a uid using a macro CRTOUID 695f476c6edSMauro Carvalho Chehab (this macro is platform dependent). Upon success the VFid and 696f476c6edSMauro Carvalho Chehab attributes of the file are returned. The Coda FS Driver will normally 697f476c6edSMauro Carvalho Chehab instantiate a vnode, inode or file handle at kernel level for the new 698f476c6edSMauro Carvalho Chehab object. 699f476c6edSMauro Carvalho Chehab 700f476c6edSMauro Carvalho Chehab 701f476c6edSMauro Carvalho Chehab Errors 702f476c6edSMauro Carvalho Chehab A variety of errors can occur. Permissions may be insufficient. 703f476c6edSMauro Carvalho Chehab If the object exists and is not a file the error EISDIR is returned 704f476c6edSMauro Carvalho Chehab under Unix. 705f476c6edSMauro Carvalho Chehab 706f476c6edSMauro Carvalho Chehab .. Note:: 707f476c6edSMauro Carvalho Chehab 708f476c6edSMauro Carvalho Chehab The packing of parameters is very inefficient and appears to 709f476c6edSMauro Carvalho Chehab indicate confusion between the system call creat and the VFS operation 710f476c6edSMauro Carvalho Chehab create. The VFS operation create is only called to create new objects. 711f476c6edSMauro Carvalho Chehab This create call differs from the Unix one in that it is not invoked 712f476c6edSMauro Carvalho Chehab to return a file descriptor. The truncate and exclusive options, 713f476c6edSMauro Carvalho Chehab together with the mode, could simply be part of the mode as it is 714f476c6edSMauro Carvalho Chehab under Unix. There should be no flags argument; this is used in open 715f476c6edSMauro Carvalho Chehab (2) to return a file descriptor for READ or WRITE mode. 716f476c6edSMauro Carvalho Chehab 717f476c6edSMauro Carvalho Chehab The attributes of the directory should be returned too, since the size 718f476c6edSMauro Carvalho Chehab and mtime changed. 719f476c6edSMauro Carvalho Chehab 720f476c6edSMauro Carvalho Chehab 721f476c6edSMauro Carvalho Chehab4.9. mkdir 722f476c6edSMauro Carvalho Chehab----------- 723f476c6edSMauro Carvalho Chehab 724f476c6edSMauro Carvalho Chehab 725f476c6edSMauro Carvalho Chehab Summary 726f476c6edSMauro Carvalho Chehab Create a new directory. 727f476c6edSMauro Carvalho Chehab 728f476c6edSMauro Carvalho Chehab Arguments 729f476c6edSMauro Carvalho Chehab in:: 730f476c6edSMauro Carvalho Chehab 731f476c6edSMauro Carvalho Chehab struct cfs_mkdir_in { 732f476c6edSMauro Carvalho Chehab ViceFid VFid; 733f476c6edSMauro Carvalho Chehab struct coda_vattr attr; 734f476c6edSMauro Carvalho Chehab char *name; /* Place holder for data. */ 735f476c6edSMauro Carvalho Chehab } cfs_mkdir; 736f476c6edSMauro Carvalho Chehab 737f476c6edSMauro Carvalho Chehab 738f476c6edSMauro Carvalho Chehab 739f476c6edSMauro Carvalho Chehab out:: 740f476c6edSMauro Carvalho Chehab 741f476c6edSMauro Carvalho Chehab struct cfs_mkdir_out { 742f476c6edSMauro Carvalho Chehab ViceFid VFid; 743f476c6edSMauro Carvalho Chehab struct coda_vattr attr; 744f476c6edSMauro Carvalho Chehab } cfs_mkdir; 745f476c6edSMauro Carvalho Chehab 746f476c6edSMauro Carvalho Chehab 747f476c6edSMauro Carvalho Chehab 748f476c6edSMauro Carvalho Chehab 749f476c6edSMauro Carvalho Chehab Description 750f476c6edSMauro Carvalho Chehab This call is similar to create but creates a directory. 751f476c6edSMauro Carvalho Chehab Only the mode field in the input parameters is used for creation. 752f476c6edSMauro Carvalho Chehab Upon successful creation, the attr returned contains the attributes of 753f476c6edSMauro Carvalho Chehab the new directory. 754f476c6edSMauro Carvalho Chehab 755f476c6edSMauro Carvalho Chehab Errors 756f476c6edSMauro Carvalho Chehab As for create. 757f476c6edSMauro Carvalho Chehab 758f476c6edSMauro Carvalho Chehab .. Note:: 759f476c6edSMauro Carvalho Chehab 760f476c6edSMauro Carvalho Chehab The input parameter should be changed to mode instead of 761f476c6edSMauro Carvalho Chehab attributes. 762f476c6edSMauro Carvalho Chehab 763f476c6edSMauro Carvalho Chehab The attributes of the parent should be returned since the size and 764f476c6edSMauro Carvalho Chehab mtime changes. 765f476c6edSMauro Carvalho Chehab 766f476c6edSMauro Carvalho Chehab 767f476c6edSMauro Carvalho Chehab4.10. link 768f476c6edSMauro Carvalho Chehab----------- 769f476c6edSMauro Carvalho Chehab 770f476c6edSMauro Carvalho Chehab 771f476c6edSMauro Carvalho Chehab Summary 772f476c6edSMauro Carvalho Chehab Create a link to an existing file. 773f476c6edSMauro Carvalho Chehab 774f476c6edSMauro Carvalho Chehab Arguments 775f476c6edSMauro Carvalho Chehab in:: 776f476c6edSMauro Carvalho Chehab 777f476c6edSMauro Carvalho Chehab struct cfs_link_in { 778f476c6edSMauro Carvalho Chehab ViceFid sourceFid; /* cnode to link *to* */ 779f476c6edSMauro Carvalho Chehab ViceFid destFid; /* Directory in which to place link */ 780f476c6edSMauro Carvalho Chehab char *tname; /* Place holder for data. */ 781f476c6edSMauro Carvalho Chehab } cfs_link; 782f476c6edSMauro Carvalho Chehab 783f476c6edSMauro Carvalho Chehab 784f476c6edSMauro Carvalho Chehab 785f476c6edSMauro Carvalho Chehab out 786f476c6edSMauro Carvalho Chehab 787f476c6edSMauro Carvalho Chehab empty 788f476c6edSMauro Carvalho Chehab 789f476c6edSMauro Carvalho Chehab Description 790f476c6edSMauro Carvalho Chehab This call creates a link to the sourceFid in the directory 791f476c6edSMauro Carvalho Chehab identified by destFid with name tname. The source must reside in the 792f476c6edSMauro Carvalho Chehab target's parent, i.e. the source must be have parent destFid, i.e. Coda 793f476c6edSMauro Carvalho Chehab does not support cross directory hard links. Only the return value is 794f476c6edSMauro Carvalho Chehab relevant. It indicates success or the type of failure. 795f476c6edSMauro Carvalho Chehab 796f476c6edSMauro Carvalho Chehab Errors 797f476c6edSMauro Carvalho Chehab The usual errors can occur. 798f476c6edSMauro Carvalho Chehab 799f476c6edSMauro Carvalho Chehab 800f476c6edSMauro Carvalho Chehab4.11. symlink 801f476c6edSMauro Carvalho Chehab-------------- 802f476c6edSMauro Carvalho Chehab 803f476c6edSMauro Carvalho Chehab 804f476c6edSMauro Carvalho Chehab Summary 805f476c6edSMauro Carvalho Chehab create a symbolic link 806f476c6edSMauro Carvalho Chehab 807f476c6edSMauro Carvalho Chehab Arguments 808f476c6edSMauro Carvalho Chehab in:: 809f476c6edSMauro Carvalho Chehab 810f476c6edSMauro Carvalho Chehab struct cfs_symlink_in { 811f476c6edSMauro Carvalho Chehab ViceFid VFid; /* Directory to put symlink in */ 812f476c6edSMauro Carvalho Chehab char *srcname; 813f476c6edSMauro Carvalho Chehab struct coda_vattr attr; 814f476c6edSMauro Carvalho Chehab char *tname; 815f476c6edSMauro Carvalho Chehab } cfs_symlink; 816f476c6edSMauro Carvalho Chehab 817f476c6edSMauro Carvalho Chehab 818f476c6edSMauro Carvalho Chehab 819f476c6edSMauro Carvalho Chehab out 820f476c6edSMauro Carvalho Chehab 821f476c6edSMauro Carvalho Chehab none 822f476c6edSMauro Carvalho Chehab 823f476c6edSMauro Carvalho Chehab Description 824f476c6edSMauro Carvalho Chehab Create a symbolic link. The link is to be placed in the 825f476c6edSMauro Carvalho Chehab directory identified by VFid and named tname. It should point to the 826f476c6edSMauro Carvalho Chehab pathname srcname. The attributes of the newly created object are to 827f476c6edSMauro Carvalho Chehab be set to attr. 828f476c6edSMauro Carvalho Chehab 829f476c6edSMauro Carvalho Chehab .. Note:: 830f476c6edSMauro Carvalho Chehab 831f476c6edSMauro Carvalho Chehab The attributes of the target directory should be returned since 832f476c6edSMauro Carvalho Chehab its size changed. 833f476c6edSMauro Carvalho Chehab 834f476c6edSMauro Carvalho Chehab 835f476c6edSMauro Carvalho Chehab4.12. remove 836f476c6edSMauro Carvalho Chehab------------- 837f476c6edSMauro Carvalho Chehab 838f476c6edSMauro Carvalho Chehab 839f476c6edSMauro Carvalho Chehab Summary 840f476c6edSMauro Carvalho Chehab Remove a file 841f476c6edSMauro Carvalho Chehab 842f476c6edSMauro Carvalho Chehab Arguments 843f476c6edSMauro Carvalho Chehab in:: 844f476c6edSMauro Carvalho Chehab 845f476c6edSMauro Carvalho Chehab struct cfs_remove_in { 846f476c6edSMauro Carvalho Chehab ViceFid VFid; 847f476c6edSMauro Carvalho Chehab char *name; /* Place holder for data. */ 848f476c6edSMauro Carvalho Chehab } cfs_remove; 849f476c6edSMauro Carvalho Chehab 850f476c6edSMauro Carvalho Chehab 851f476c6edSMauro Carvalho Chehab 852f476c6edSMauro Carvalho Chehab out 853f476c6edSMauro Carvalho Chehab 854f476c6edSMauro Carvalho Chehab none 855f476c6edSMauro Carvalho Chehab 856f476c6edSMauro Carvalho Chehab Description 857f476c6edSMauro Carvalho Chehab Remove file named cfs_remove_in.name in directory 858f476c6edSMauro Carvalho Chehab identified by VFid. 859f476c6edSMauro Carvalho Chehab 860f476c6edSMauro Carvalho Chehab 861f476c6edSMauro Carvalho Chehab .. Note:: 862f476c6edSMauro Carvalho Chehab 863f476c6edSMauro Carvalho Chehab The attributes of the directory should be returned since its 864f476c6edSMauro Carvalho Chehab mtime and size may change. 865f476c6edSMauro Carvalho Chehab 866f476c6edSMauro Carvalho Chehab 867f476c6edSMauro Carvalho Chehab4.13. rmdir 868f476c6edSMauro Carvalho Chehab------------ 869f476c6edSMauro Carvalho Chehab 870f476c6edSMauro Carvalho Chehab 871f476c6edSMauro Carvalho Chehab Summary 872f476c6edSMauro Carvalho Chehab Remove a directory 873f476c6edSMauro Carvalho Chehab 874f476c6edSMauro Carvalho Chehab Arguments 875f476c6edSMauro Carvalho Chehab in:: 876f476c6edSMauro Carvalho Chehab 877f476c6edSMauro Carvalho Chehab struct cfs_rmdir_in { 878f476c6edSMauro Carvalho Chehab ViceFid VFid; 879f476c6edSMauro Carvalho Chehab char *name; /* Place holder for data. */ 880f476c6edSMauro Carvalho Chehab } cfs_rmdir; 881f476c6edSMauro Carvalho Chehab 882f476c6edSMauro Carvalho Chehab 883f476c6edSMauro Carvalho Chehab 884f476c6edSMauro Carvalho Chehab out 885f476c6edSMauro Carvalho Chehab 886f476c6edSMauro Carvalho Chehab none 887f476c6edSMauro Carvalho Chehab 888f476c6edSMauro Carvalho Chehab Description 8894b708d6eSRandy Dunlap Remove the directory with name 'name' from the directory 890f476c6edSMauro Carvalho Chehab identified by VFid. 891f476c6edSMauro Carvalho Chehab 892f476c6edSMauro Carvalho Chehab .. Note:: The attributes of the parent directory should be returned since 893f476c6edSMauro Carvalho Chehab its mtime and size may change. 894f476c6edSMauro Carvalho Chehab 895f476c6edSMauro Carvalho Chehab 896f476c6edSMauro Carvalho Chehab4.14. readlink 897f476c6edSMauro Carvalho Chehab--------------- 898f476c6edSMauro Carvalho Chehab 899f476c6edSMauro Carvalho Chehab 900f476c6edSMauro Carvalho Chehab Summary 901f476c6edSMauro Carvalho Chehab Read the value of a symbolic link. 902f476c6edSMauro Carvalho Chehab 903f476c6edSMauro Carvalho Chehab Arguments 904f476c6edSMauro Carvalho Chehab in:: 905f476c6edSMauro Carvalho Chehab 906f476c6edSMauro Carvalho Chehab struct cfs_readlink_in { 907f476c6edSMauro Carvalho Chehab ViceFid VFid; 908f476c6edSMauro Carvalho Chehab } cfs_readlink; 909f476c6edSMauro Carvalho Chehab 910f476c6edSMauro Carvalho Chehab 911f476c6edSMauro Carvalho Chehab 912f476c6edSMauro Carvalho Chehab out:: 913f476c6edSMauro Carvalho Chehab 914f476c6edSMauro Carvalho Chehab struct cfs_readlink_out { 915f476c6edSMauro Carvalho Chehab int count; 916f476c6edSMauro Carvalho Chehab caddr_t data; /* Place holder for data. */ 917f476c6edSMauro Carvalho Chehab } cfs_readlink; 918f476c6edSMauro Carvalho Chehab 919f476c6edSMauro Carvalho Chehab 920f476c6edSMauro Carvalho Chehab 921f476c6edSMauro Carvalho Chehab Description 922f476c6edSMauro Carvalho Chehab This routine reads the contents of symbolic link 923f476c6edSMauro Carvalho Chehab identified by VFid into the buffer data. The buffer data must be able 924f476c6edSMauro Carvalho Chehab to hold any name up to CFS_MAXNAMLEN (PATH or NAM??). 925f476c6edSMauro Carvalho Chehab 926f476c6edSMauro Carvalho Chehab Errors 927f476c6edSMauro Carvalho Chehab No unusual errors. 928f476c6edSMauro Carvalho Chehab 929f476c6edSMauro Carvalho Chehab 930f476c6edSMauro Carvalho Chehab4.15. open 931f476c6edSMauro Carvalho Chehab----------- 932f476c6edSMauro Carvalho Chehab 933f476c6edSMauro Carvalho Chehab 934f476c6edSMauro Carvalho Chehab Summary 935f476c6edSMauro Carvalho Chehab Open a file. 936f476c6edSMauro Carvalho Chehab 937f476c6edSMauro Carvalho Chehab Arguments 938f476c6edSMauro Carvalho Chehab in:: 939f476c6edSMauro Carvalho Chehab 940f476c6edSMauro Carvalho Chehab struct cfs_open_in { 941f476c6edSMauro Carvalho Chehab ViceFid VFid; 942f476c6edSMauro Carvalho Chehab int flags; 943f476c6edSMauro Carvalho Chehab } cfs_open; 944f476c6edSMauro Carvalho Chehab 945f476c6edSMauro Carvalho Chehab 946f476c6edSMauro Carvalho Chehab 947f476c6edSMauro Carvalho Chehab out:: 948f476c6edSMauro Carvalho Chehab 949f476c6edSMauro Carvalho Chehab struct cfs_open_out { 950f476c6edSMauro Carvalho Chehab dev_t dev; 951f476c6edSMauro Carvalho Chehab ino_t inode; 952f476c6edSMauro Carvalho Chehab } cfs_open; 953f476c6edSMauro Carvalho Chehab 954f476c6edSMauro Carvalho Chehab 955f476c6edSMauro Carvalho Chehab 956f476c6edSMauro Carvalho Chehab Description 957f476c6edSMauro Carvalho Chehab This request asks Venus to place the file identified by 958f476c6edSMauro Carvalho Chehab VFid in its cache and to note that the calling process wishes to open 959f476c6edSMauro Carvalho Chehab it with flags as in open(2). The return value to the kernel differs 960f476c6edSMauro Carvalho Chehab for Unix and Windows systems. For Unix systems the Coda FS Driver is 961f476c6edSMauro Carvalho Chehab informed of the device and inode number of the container file in the 962f476c6edSMauro Carvalho Chehab fields dev and inode. For Windows the path of the container file is 963f476c6edSMauro Carvalho Chehab returned to the kernel. 964f476c6edSMauro Carvalho Chehab 965f476c6edSMauro Carvalho Chehab 966f476c6edSMauro Carvalho Chehab .. Note:: 967f476c6edSMauro Carvalho Chehab 968f476c6edSMauro Carvalho Chehab Currently the cfs_open_out structure is not properly adapted to 969f476c6edSMauro Carvalho Chehab deal with the Windows case. It might be best to implement two 970f476c6edSMauro Carvalho Chehab upcalls, one to open aiming at a container file name, the other at a 971f476c6edSMauro Carvalho Chehab container file inode. 972f476c6edSMauro Carvalho Chehab 973f476c6edSMauro Carvalho Chehab 974f476c6edSMauro Carvalho Chehab4.16. close 975f476c6edSMauro Carvalho Chehab------------ 976f476c6edSMauro Carvalho Chehab 977f476c6edSMauro Carvalho Chehab 978f476c6edSMauro Carvalho Chehab Summary 979f476c6edSMauro Carvalho Chehab Close a file, update it on the servers. 980f476c6edSMauro Carvalho Chehab 981f476c6edSMauro Carvalho Chehab Arguments 982f476c6edSMauro Carvalho Chehab in:: 983f476c6edSMauro Carvalho Chehab 984f476c6edSMauro Carvalho Chehab struct cfs_close_in { 985f476c6edSMauro Carvalho Chehab ViceFid VFid; 986f476c6edSMauro Carvalho Chehab int flags; 987f476c6edSMauro Carvalho Chehab } cfs_close; 988f476c6edSMauro Carvalho Chehab 989f476c6edSMauro Carvalho Chehab 990f476c6edSMauro Carvalho Chehab 991f476c6edSMauro Carvalho Chehab out 992f476c6edSMauro Carvalho Chehab 993f476c6edSMauro Carvalho Chehab none 994f476c6edSMauro Carvalho Chehab 995f476c6edSMauro Carvalho Chehab Description 996f476c6edSMauro Carvalho Chehab Close the file identified by VFid. 997f476c6edSMauro Carvalho Chehab 998f476c6edSMauro Carvalho Chehab .. Note:: 999f476c6edSMauro Carvalho Chehab 1000f476c6edSMauro Carvalho Chehab The flags argument is bogus and not used. However, Venus' code 1001f476c6edSMauro Carvalho Chehab has room to deal with an execp input field, probably this field should 1002f476c6edSMauro Carvalho Chehab be used to inform Venus that the file was closed but is still memory 1003f476c6edSMauro Carvalho Chehab mapped for execution. There are comments about fetching versus not 1004f476c6edSMauro Carvalho Chehab fetching the data in Venus vproc_vfscalls. This seems silly. If a 1005f476c6edSMauro Carvalho Chehab file is being closed, the data in the container file is to be the new 1006f476c6edSMauro Carvalho Chehab data. Here again the execp flag might be in play to create confusion: 1007f476c6edSMauro Carvalho Chehab currently Venus might think a file can be flushed from the cache when 1008f476c6edSMauro Carvalho Chehab it is still memory mapped. This needs to be understood. 1009f476c6edSMauro Carvalho Chehab 1010f476c6edSMauro Carvalho Chehab 1011f476c6edSMauro Carvalho Chehab4.17. ioctl 1012f476c6edSMauro Carvalho Chehab------------ 1013f476c6edSMauro Carvalho Chehab 1014f476c6edSMauro Carvalho Chehab 1015f476c6edSMauro Carvalho Chehab Summary 1016f476c6edSMauro Carvalho Chehab Do an ioctl on a file. This includes the pioctl interface. 1017f476c6edSMauro Carvalho Chehab 1018f476c6edSMauro Carvalho Chehab Arguments 1019f476c6edSMauro Carvalho Chehab in:: 1020f476c6edSMauro Carvalho Chehab 1021f476c6edSMauro Carvalho Chehab struct cfs_ioctl_in { 1022f476c6edSMauro Carvalho Chehab ViceFid VFid; 1023f476c6edSMauro Carvalho Chehab int cmd; 1024f476c6edSMauro Carvalho Chehab int len; 1025f476c6edSMauro Carvalho Chehab int rwflag; 1026f476c6edSMauro Carvalho Chehab char *data; /* Place holder for data. */ 1027f476c6edSMauro Carvalho Chehab } cfs_ioctl; 1028f476c6edSMauro Carvalho Chehab 1029f476c6edSMauro Carvalho Chehab 1030f476c6edSMauro Carvalho Chehab 1031f476c6edSMauro Carvalho Chehab out:: 1032f476c6edSMauro Carvalho Chehab 1033f476c6edSMauro Carvalho Chehab 1034f476c6edSMauro Carvalho Chehab struct cfs_ioctl_out { 1035f476c6edSMauro Carvalho Chehab int len; 1036f476c6edSMauro Carvalho Chehab caddr_t data; /* Place holder for data. */ 1037f476c6edSMauro Carvalho Chehab } cfs_ioctl; 1038f476c6edSMauro Carvalho Chehab 1039f476c6edSMauro Carvalho Chehab 1040f476c6edSMauro Carvalho Chehab 1041f476c6edSMauro Carvalho Chehab Description 1042f476c6edSMauro Carvalho Chehab Do an ioctl operation on a file. The command, len and 1043f476c6edSMauro Carvalho Chehab data arguments are filled as usual. flags is not used by Venus. 1044f476c6edSMauro Carvalho Chehab 1045f476c6edSMauro Carvalho Chehab .. Note:: 1046f476c6edSMauro Carvalho Chehab 1047f476c6edSMauro Carvalho Chehab Another bogus parameter. flags is not used. What is the 1048f476c6edSMauro Carvalho Chehab business about PREFETCHING in the Venus code? 1049f476c6edSMauro Carvalho Chehab 1050f476c6edSMauro Carvalho Chehab 1051f476c6edSMauro Carvalho Chehab 1052f476c6edSMauro Carvalho Chehab4.18. rename 1053f476c6edSMauro Carvalho Chehab------------- 1054f476c6edSMauro Carvalho Chehab 1055f476c6edSMauro Carvalho Chehab 1056f476c6edSMauro Carvalho Chehab Summary 1057f476c6edSMauro Carvalho Chehab Rename a fid. 1058f476c6edSMauro Carvalho Chehab 1059f476c6edSMauro Carvalho Chehab Arguments 1060f476c6edSMauro Carvalho Chehab in:: 1061f476c6edSMauro Carvalho Chehab 1062f476c6edSMauro Carvalho Chehab struct cfs_rename_in { 1063f476c6edSMauro Carvalho Chehab ViceFid sourceFid; 1064f476c6edSMauro Carvalho Chehab char *srcname; 1065f476c6edSMauro Carvalho Chehab ViceFid destFid; 1066f476c6edSMauro Carvalho Chehab char *destname; 1067f476c6edSMauro Carvalho Chehab } cfs_rename; 1068f476c6edSMauro Carvalho Chehab 1069f476c6edSMauro Carvalho Chehab 1070f476c6edSMauro Carvalho Chehab 1071f476c6edSMauro Carvalho Chehab out 1072f476c6edSMauro Carvalho Chehab 1073f476c6edSMauro Carvalho Chehab none 1074f476c6edSMauro Carvalho Chehab 1075f476c6edSMauro Carvalho Chehab Description 1076f476c6edSMauro Carvalho Chehab Rename the object with name srcname in directory 1077f476c6edSMauro Carvalho Chehab sourceFid to destname in destFid. It is important that the names 1078f476c6edSMauro Carvalho Chehab srcname and destname are 0 terminated strings. Strings in Unix 1079f476c6edSMauro Carvalho Chehab kernels are not always null terminated. 1080f476c6edSMauro Carvalho Chehab 1081f476c6edSMauro Carvalho Chehab 1082f476c6edSMauro Carvalho Chehab4.19. readdir 1083f476c6edSMauro Carvalho Chehab-------------- 1084f476c6edSMauro Carvalho Chehab 1085f476c6edSMauro Carvalho Chehab 1086f476c6edSMauro Carvalho Chehab Summary 1087f476c6edSMauro Carvalho Chehab Read directory entries. 1088f476c6edSMauro Carvalho Chehab 1089f476c6edSMauro Carvalho Chehab Arguments 1090f476c6edSMauro Carvalho Chehab in:: 1091f476c6edSMauro Carvalho Chehab 1092f476c6edSMauro Carvalho Chehab struct cfs_readdir_in { 1093f476c6edSMauro Carvalho Chehab ViceFid VFid; 1094f476c6edSMauro Carvalho Chehab int count; 1095f476c6edSMauro Carvalho Chehab int offset; 1096f476c6edSMauro Carvalho Chehab } cfs_readdir; 1097f476c6edSMauro Carvalho Chehab 1098f476c6edSMauro Carvalho Chehab 1099f476c6edSMauro Carvalho Chehab 1100f476c6edSMauro Carvalho Chehab 1101f476c6edSMauro Carvalho Chehab out:: 1102f476c6edSMauro Carvalho Chehab 1103f476c6edSMauro Carvalho Chehab struct cfs_readdir_out { 1104f476c6edSMauro Carvalho Chehab int size; 1105f476c6edSMauro Carvalho Chehab caddr_t data; /* Place holder for data. */ 1106f476c6edSMauro Carvalho Chehab } cfs_readdir; 1107f476c6edSMauro Carvalho Chehab 1108f476c6edSMauro Carvalho Chehab 1109f476c6edSMauro Carvalho Chehab 1110f476c6edSMauro Carvalho Chehab Description 1111f476c6edSMauro Carvalho Chehab Read directory entries from VFid starting at offset and 1112f476c6edSMauro Carvalho Chehab read at most count bytes. Returns the data in data and returns 1113f476c6edSMauro Carvalho Chehab the size in size. 1114f476c6edSMauro Carvalho Chehab 1115f476c6edSMauro Carvalho Chehab 1116f476c6edSMauro Carvalho Chehab .. Note:: 1117f476c6edSMauro Carvalho Chehab 1118f476c6edSMauro Carvalho Chehab This call is not used. Readdir operations exploit container 1119f476c6edSMauro Carvalho Chehab files. We will re-evaluate this during the directory revamp which is 1120f476c6edSMauro Carvalho Chehab about to take place. 1121f476c6edSMauro Carvalho Chehab 1122f476c6edSMauro Carvalho Chehab 1123f476c6edSMauro Carvalho Chehab4.20. vget 1124f476c6edSMauro Carvalho Chehab----------- 1125f476c6edSMauro Carvalho Chehab 1126f476c6edSMauro Carvalho Chehab 1127f476c6edSMauro Carvalho Chehab Summary 1128f476c6edSMauro Carvalho Chehab instructs Venus to do an FSDB->Get. 1129f476c6edSMauro Carvalho Chehab 1130f476c6edSMauro Carvalho Chehab Arguments 1131f476c6edSMauro Carvalho Chehab in:: 1132f476c6edSMauro Carvalho Chehab 1133f476c6edSMauro Carvalho Chehab struct cfs_vget_in { 1134f476c6edSMauro Carvalho Chehab ViceFid VFid; 1135f476c6edSMauro Carvalho Chehab } cfs_vget; 1136f476c6edSMauro Carvalho Chehab 1137f476c6edSMauro Carvalho Chehab 1138f476c6edSMauro Carvalho Chehab 1139f476c6edSMauro Carvalho Chehab out:: 1140f476c6edSMauro Carvalho Chehab 1141f476c6edSMauro Carvalho Chehab struct cfs_vget_out { 1142f476c6edSMauro Carvalho Chehab ViceFid VFid; 1143f476c6edSMauro Carvalho Chehab int vtype; 1144f476c6edSMauro Carvalho Chehab } cfs_vget; 1145f476c6edSMauro Carvalho Chehab 1146f476c6edSMauro Carvalho Chehab 1147f476c6edSMauro Carvalho Chehab 1148f476c6edSMauro Carvalho Chehab Description 1149f476c6edSMauro Carvalho Chehab This upcall asks Venus to do a get operation on an fsobj 1150f476c6edSMauro Carvalho Chehab labelled by VFid. 1151f476c6edSMauro Carvalho Chehab 1152f476c6edSMauro Carvalho Chehab .. Note:: 1153f476c6edSMauro Carvalho Chehab 1154f476c6edSMauro Carvalho Chehab This operation is not used. However, it is extremely useful 1155f476c6edSMauro Carvalho Chehab since it can be used to deal with read/write memory mapped files. 1156f476c6edSMauro Carvalho Chehab These can be "pinned" in the Venus cache using vget and released with 1157f476c6edSMauro Carvalho Chehab inactive. 1158f476c6edSMauro Carvalho Chehab 1159f476c6edSMauro Carvalho Chehab 1160f476c6edSMauro Carvalho Chehab4.21. fsync 1161f476c6edSMauro Carvalho Chehab------------ 1162f476c6edSMauro Carvalho Chehab 1163f476c6edSMauro Carvalho Chehab 1164f476c6edSMauro Carvalho Chehab Summary 1165f476c6edSMauro Carvalho Chehab Tell Venus to update the RVM attributes of a file. 1166f476c6edSMauro Carvalho Chehab 1167f476c6edSMauro Carvalho Chehab Arguments 1168f476c6edSMauro Carvalho Chehab in:: 1169f476c6edSMauro Carvalho Chehab 1170f476c6edSMauro Carvalho Chehab struct cfs_fsync_in { 1171f476c6edSMauro Carvalho Chehab ViceFid VFid; 1172f476c6edSMauro Carvalho Chehab } cfs_fsync; 1173f476c6edSMauro Carvalho Chehab 1174f476c6edSMauro Carvalho Chehab 1175f476c6edSMauro Carvalho Chehab 1176f476c6edSMauro Carvalho Chehab out 1177f476c6edSMauro Carvalho Chehab 1178f476c6edSMauro Carvalho Chehab none 1179f476c6edSMauro Carvalho Chehab 1180f476c6edSMauro Carvalho Chehab Description 1181f476c6edSMauro Carvalho Chehab Ask Venus to update RVM attributes of object VFid. This 1182f476c6edSMauro Carvalho Chehab should be called as part of kernel level fsync type calls. The 1183f476c6edSMauro Carvalho Chehab result indicates if the syncing was successful. 1184f476c6edSMauro Carvalho Chehab 1185f476c6edSMauro Carvalho Chehab .. Note:: Linux does not implement this call. It should. 1186f476c6edSMauro Carvalho Chehab 1187f476c6edSMauro Carvalho Chehab 1188f476c6edSMauro Carvalho Chehab4.22. inactive 1189f476c6edSMauro Carvalho Chehab--------------- 1190f476c6edSMauro Carvalho Chehab 1191f476c6edSMauro Carvalho Chehab 1192f476c6edSMauro Carvalho Chehab Summary 1193f476c6edSMauro Carvalho Chehab Tell Venus a vnode is no longer in use. 1194f476c6edSMauro Carvalho Chehab 1195f476c6edSMauro Carvalho Chehab Arguments 1196f476c6edSMauro Carvalho Chehab in:: 1197f476c6edSMauro Carvalho Chehab 1198f476c6edSMauro Carvalho Chehab struct cfs_inactive_in { 1199f476c6edSMauro Carvalho Chehab ViceFid VFid; 1200f476c6edSMauro Carvalho Chehab } cfs_inactive; 1201f476c6edSMauro Carvalho Chehab 1202f476c6edSMauro Carvalho Chehab 1203f476c6edSMauro Carvalho Chehab 1204f476c6edSMauro Carvalho Chehab out 1205f476c6edSMauro Carvalho Chehab 1206f476c6edSMauro Carvalho Chehab none 1207f476c6edSMauro Carvalho Chehab 1208f476c6edSMauro Carvalho Chehab Description 1209f476c6edSMauro Carvalho Chehab This operation returns EOPNOTSUPP. 1210f476c6edSMauro Carvalho Chehab 1211f476c6edSMauro Carvalho Chehab .. Note:: This should perhaps be removed. 1212f476c6edSMauro Carvalho Chehab 1213f476c6edSMauro Carvalho Chehab 1214f476c6edSMauro Carvalho Chehab4.23. rdwr 1215f476c6edSMauro Carvalho Chehab----------- 1216f476c6edSMauro Carvalho Chehab 1217f476c6edSMauro Carvalho Chehab 1218f476c6edSMauro Carvalho Chehab Summary 1219f476c6edSMauro Carvalho Chehab Read or write from a file 1220f476c6edSMauro Carvalho Chehab 1221f476c6edSMauro Carvalho Chehab Arguments 1222f476c6edSMauro Carvalho Chehab in:: 1223f476c6edSMauro Carvalho Chehab 1224f476c6edSMauro Carvalho Chehab struct cfs_rdwr_in { 1225f476c6edSMauro Carvalho Chehab ViceFid VFid; 1226f476c6edSMauro Carvalho Chehab int rwflag; 1227f476c6edSMauro Carvalho Chehab int count; 1228f476c6edSMauro Carvalho Chehab int offset; 1229f476c6edSMauro Carvalho Chehab int ioflag; 1230f476c6edSMauro Carvalho Chehab caddr_t data; /* Place holder for data. */ 1231f476c6edSMauro Carvalho Chehab } cfs_rdwr; 1232f476c6edSMauro Carvalho Chehab 1233f476c6edSMauro Carvalho Chehab 1234f476c6edSMauro Carvalho Chehab 1235f476c6edSMauro Carvalho Chehab 1236f476c6edSMauro Carvalho Chehab out:: 1237f476c6edSMauro Carvalho Chehab 1238f476c6edSMauro Carvalho Chehab struct cfs_rdwr_out { 1239f476c6edSMauro Carvalho Chehab int rwflag; 1240f476c6edSMauro Carvalho Chehab int count; 1241f476c6edSMauro Carvalho Chehab caddr_t data; /* Place holder for data. */ 1242f476c6edSMauro Carvalho Chehab } cfs_rdwr; 1243f476c6edSMauro Carvalho Chehab 1244f476c6edSMauro Carvalho Chehab 1245f476c6edSMauro Carvalho Chehab 1246f476c6edSMauro Carvalho Chehab Description 1247f476c6edSMauro Carvalho Chehab This upcall asks Venus to read or write from a file. 1248f476c6edSMauro Carvalho Chehab 1249f476c6edSMauro Carvalho Chehab 1250f476c6edSMauro Carvalho Chehab .. Note:: 1251f476c6edSMauro Carvalho Chehab 1252f476c6edSMauro Carvalho Chehab It should be removed since it is against the Coda philosophy that 1253f476c6edSMauro Carvalho Chehab read/write operations never reach Venus. I have been told the 1254f476c6edSMauro Carvalho Chehab operation does not work. It is not currently used. 1255f476c6edSMauro Carvalho Chehab 1256f476c6edSMauro Carvalho Chehab 1257f476c6edSMauro Carvalho Chehab 1258f476c6edSMauro Carvalho Chehab4.24. odymount 1259f476c6edSMauro Carvalho Chehab--------------- 1260f476c6edSMauro Carvalho Chehab 1261f476c6edSMauro Carvalho Chehab 1262f476c6edSMauro Carvalho Chehab Summary 1263f476c6edSMauro Carvalho Chehab Allows mounting multiple Coda "filesystems" on one Unix mount point. 1264f476c6edSMauro Carvalho Chehab 1265f476c6edSMauro Carvalho Chehab Arguments 1266f476c6edSMauro Carvalho Chehab in:: 1267f476c6edSMauro Carvalho Chehab 1268f476c6edSMauro Carvalho Chehab struct ody_mount_in { 1269f476c6edSMauro Carvalho Chehab char *name; /* Place holder for data. */ 1270f476c6edSMauro Carvalho Chehab } ody_mount; 1271f476c6edSMauro Carvalho Chehab 1272f476c6edSMauro Carvalho Chehab 1273f476c6edSMauro Carvalho Chehab 1274f476c6edSMauro Carvalho Chehab out:: 1275f476c6edSMauro Carvalho Chehab 1276f476c6edSMauro Carvalho Chehab struct ody_mount_out { 1277f476c6edSMauro Carvalho Chehab ViceFid VFid; 1278f476c6edSMauro Carvalho Chehab } ody_mount; 1279f476c6edSMauro Carvalho Chehab 1280f476c6edSMauro Carvalho Chehab 1281f476c6edSMauro Carvalho Chehab 1282f476c6edSMauro Carvalho Chehab Description 1283f476c6edSMauro Carvalho Chehab Asks Venus to return the rootfid of a Coda system named 1284f476c6edSMauro Carvalho Chehab name. The fid is returned in VFid. 1285f476c6edSMauro Carvalho Chehab 1286f476c6edSMauro Carvalho Chehab .. Note:: 1287f476c6edSMauro Carvalho Chehab 1288f476c6edSMauro Carvalho Chehab This call was used by David for dynamic sets. It should be 1289f476c6edSMauro Carvalho Chehab removed since it causes a jungle of pointers in the VFS mounting area. 1290f476c6edSMauro Carvalho Chehab It is not used by Coda proper. Call is not implemented by Venus. 1291f476c6edSMauro Carvalho Chehab 1292f476c6edSMauro Carvalho Chehab 1293f476c6edSMauro Carvalho Chehab4.25. ody_lookup 1294f476c6edSMauro Carvalho Chehab----------------- 1295f476c6edSMauro Carvalho Chehab 1296f476c6edSMauro Carvalho Chehab 1297f476c6edSMauro Carvalho Chehab Summary 1298f476c6edSMauro Carvalho Chehab Looks up something. 1299f476c6edSMauro Carvalho Chehab 1300f476c6edSMauro Carvalho Chehab Arguments 1301f476c6edSMauro Carvalho Chehab in 1302f476c6edSMauro Carvalho Chehab 1303f476c6edSMauro Carvalho Chehab irrelevant 1304f476c6edSMauro Carvalho Chehab 1305f476c6edSMauro Carvalho Chehab 1306f476c6edSMauro Carvalho Chehab out 1307f476c6edSMauro Carvalho Chehab 1308f476c6edSMauro Carvalho Chehab irrelevant 1309f476c6edSMauro Carvalho Chehab 1310f476c6edSMauro Carvalho Chehab 1311f476c6edSMauro Carvalho Chehab .. Note:: Gut it. Call is not implemented by Venus. 1312f476c6edSMauro Carvalho Chehab 1313f476c6edSMauro Carvalho Chehab 1314f476c6edSMauro Carvalho Chehab4.26. ody_expand 1315f476c6edSMauro Carvalho Chehab----------------- 1316f476c6edSMauro Carvalho Chehab 1317f476c6edSMauro Carvalho Chehab 1318f476c6edSMauro Carvalho Chehab Summary 1319f476c6edSMauro Carvalho Chehab expands something in a dynamic set. 1320f476c6edSMauro Carvalho Chehab 1321f476c6edSMauro Carvalho Chehab Arguments 1322f476c6edSMauro Carvalho Chehab in 1323f476c6edSMauro Carvalho Chehab 1324f476c6edSMauro Carvalho Chehab irrelevant 1325f476c6edSMauro Carvalho Chehab 1326f476c6edSMauro Carvalho Chehab out 1327f476c6edSMauro Carvalho Chehab 1328f476c6edSMauro Carvalho Chehab irrelevant 1329f476c6edSMauro Carvalho Chehab 1330f476c6edSMauro Carvalho Chehab .. Note:: Gut it. Call is not implemented by Venus. 1331f476c6edSMauro Carvalho Chehab 1332f476c6edSMauro Carvalho Chehab 1333f476c6edSMauro Carvalho Chehab4.27. prefetch 1334f476c6edSMauro Carvalho Chehab--------------- 1335f476c6edSMauro Carvalho Chehab 1336f476c6edSMauro Carvalho Chehab 1337f476c6edSMauro Carvalho Chehab Summary 1338f476c6edSMauro Carvalho Chehab Prefetch a dynamic set. 1339f476c6edSMauro Carvalho Chehab 1340f476c6edSMauro Carvalho Chehab Arguments 1341f476c6edSMauro Carvalho Chehab 1342f476c6edSMauro Carvalho Chehab in 1343f476c6edSMauro Carvalho Chehab 1344f476c6edSMauro Carvalho Chehab Not documented. 1345f476c6edSMauro Carvalho Chehab 1346f476c6edSMauro Carvalho Chehab out 1347f476c6edSMauro Carvalho Chehab 1348f476c6edSMauro Carvalho Chehab Not documented. 1349f476c6edSMauro Carvalho Chehab 1350f476c6edSMauro Carvalho Chehab Description 1351f476c6edSMauro Carvalho Chehab Venus worker.cc has support for this call, although it is 1352f476c6edSMauro Carvalho Chehab noted that it doesn't work. Not surprising, since the kernel does not 1353f476c6edSMauro Carvalho Chehab have support for it. (ODY_PREFETCH is not a defined operation). 1354f476c6edSMauro Carvalho Chehab 1355f476c6edSMauro Carvalho Chehab 1356f476c6edSMauro Carvalho Chehab .. Note:: Gut it. It isn't working and isn't used by Coda. 1357f476c6edSMauro Carvalho Chehab 1358f476c6edSMauro Carvalho Chehab 1359f476c6edSMauro Carvalho Chehab 1360f476c6edSMauro Carvalho Chehab4.28. signal 1361f476c6edSMauro Carvalho Chehab------------- 1362f476c6edSMauro Carvalho Chehab 1363f476c6edSMauro Carvalho Chehab 1364f476c6edSMauro Carvalho Chehab Summary 1365f476c6edSMauro Carvalho Chehab Send Venus a signal about an upcall. 1366f476c6edSMauro Carvalho Chehab 1367f476c6edSMauro Carvalho Chehab Arguments 1368f476c6edSMauro Carvalho Chehab in 1369f476c6edSMauro Carvalho Chehab 1370f476c6edSMauro Carvalho Chehab none 1371f476c6edSMauro Carvalho Chehab 1372f476c6edSMauro Carvalho Chehab out 1373f476c6edSMauro Carvalho Chehab 1374f476c6edSMauro Carvalho Chehab not applicable. 1375f476c6edSMauro Carvalho Chehab 1376f476c6edSMauro Carvalho Chehab Description 1377f476c6edSMauro Carvalho Chehab This is an out-of-band upcall to Venus to inform Venus 1378f476c6edSMauro Carvalho Chehab that the calling process received a signal after Venus read the 1379f476c6edSMauro Carvalho Chehab message from the input queue. Venus is supposed to clean up the 1380f476c6edSMauro Carvalho Chehab operation. 1381f476c6edSMauro Carvalho Chehab 1382f476c6edSMauro Carvalho Chehab Errors 1383f476c6edSMauro Carvalho Chehab No reply is given. 1384f476c6edSMauro Carvalho Chehab 1385f476c6edSMauro Carvalho Chehab .. Note:: 1386f476c6edSMauro Carvalho Chehab 1387f476c6edSMauro Carvalho Chehab We need to better understand what Venus needs to clean up and if 1388f476c6edSMauro Carvalho Chehab it is doing this correctly. Also we need to handle multiple upcall 1389f476c6edSMauro Carvalho Chehab per system call situations correctly. It would be important to know 1390f476c6edSMauro Carvalho Chehab what state changes in Venus take place after an upcall for which the 1391f476c6edSMauro Carvalho Chehab kernel is responsible for notifying Venus to clean up (e.g. open 1392f476c6edSMauro Carvalho Chehab definitely is such a state change, but many others are maybe not). 1393f476c6edSMauro Carvalho Chehab 1394f476c6edSMauro Carvalho Chehab 1395f476c6edSMauro Carvalho Chehab5. The minicache and downcalls 1396f476c6edSMauro Carvalho Chehab=============================== 1397f476c6edSMauro Carvalho Chehab 1398f476c6edSMauro Carvalho Chehab 1399f476c6edSMauro Carvalho Chehab The Coda FS Driver can cache results of lookup and access upcalls, to 1400f476c6edSMauro Carvalho Chehab limit the frequency of upcalls. Upcalls carry a price since a process 1401f476c6edSMauro Carvalho Chehab context switch needs to take place. The counterpart of caching the 1402f476c6edSMauro Carvalho Chehab information is that Venus will notify the FS Driver that cached 1403f476c6edSMauro Carvalho Chehab entries must be flushed or renamed. 1404f476c6edSMauro Carvalho Chehab 1405f476c6edSMauro Carvalho Chehab The kernel code generally has to maintain a structure which links the 1406f476c6edSMauro Carvalho Chehab internal file handles (called vnodes in BSD, inodes in Linux and 1407f476c6edSMauro Carvalho Chehab FileHandles in Windows) with the ViceFid's which Venus maintains. The 1408f476c6edSMauro Carvalho Chehab reason is that frequent translations back and forth are needed in 1409f476c6edSMauro Carvalho Chehab order to make upcalls and use the results of upcalls. Such linking 1410f476c6edSMauro Carvalho Chehab objects are called cnodes. 1411f476c6edSMauro Carvalho Chehab 1412f476c6edSMauro Carvalho Chehab The current minicache implementations have cache entries which record 1413f476c6edSMauro Carvalho Chehab the following: 1414f476c6edSMauro Carvalho Chehab 1415f476c6edSMauro Carvalho Chehab 1. the name of the file 1416f476c6edSMauro Carvalho Chehab 1417f476c6edSMauro Carvalho Chehab 2. the cnode of the directory containing the object 1418f476c6edSMauro Carvalho Chehab 1419f476c6edSMauro Carvalho Chehab 3. a list of CodaCred's for which the lookup is permitted. 1420f476c6edSMauro Carvalho Chehab 1421f476c6edSMauro Carvalho Chehab 4. the cnode of the object 1422f476c6edSMauro Carvalho Chehab 1423f476c6edSMauro Carvalho Chehab The lookup call in the Coda FS Driver may request the cnode of the 1424f476c6edSMauro Carvalho Chehab desired object from the cache, by passing its name, directory and the 1425f476c6edSMauro Carvalho Chehab CodaCred's of the caller. The cache will return the cnode or indicate 1426f476c6edSMauro Carvalho Chehab that it cannot be found. The Coda FS Driver must be careful to 1427f476c6edSMauro Carvalho Chehab invalidate cache entries when it modifies or removes objects. 1428f476c6edSMauro Carvalho Chehab 1429f476c6edSMauro Carvalho Chehab When Venus obtains information that indicates that cache entries are 1430f476c6edSMauro Carvalho Chehab no longer valid, it will make a downcall to the kernel. Downcalls are 1431f476c6edSMauro Carvalho Chehab intercepted by the Coda FS Driver and lead to cache invalidations of 1432f476c6edSMauro Carvalho Chehab the kind described below. The Coda FS Driver does not return an error 1433f476c6edSMauro Carvalho Chehab unless the downcall data could not be read into kernel memory. 1434f476c6edSMauro Carvalho Chehab 1435f476c6edSMauro Carvalho Chehab 1436f476c6edSMauro Carvalho Chehab5.1. INVALIDATE 1437f476c6edSMauro Carvalho Chehab---------------- 1438f476c6edSMauro Carvalho Chehab 1439f476c6edSMauro Carvalho Chehab 1440f476c6edSMauro Carvalho Chehab No information is available on this call. 1441f476c6edSMauro Carvalho Chehab 1442f476c6edSMauro Carvalho Chehab 1443f476c6edSMauro Carvalho Chehab5.2. FLUSH 1444f476c6edSMauro Carvalho Chehab----------- 1445f476c6edSMauro Carvalho Chehab 1446f476c6edSMauro Carvalho Chehab 1447f476c6edSMauro Carvalho Chehab 1448f476c6edSMauro Carvalho Chehab Arguments 1449f476c6edSMauro Carvalho Chehab None 1450f476c6edSMauro Carvalho Chehab 1451f476c6edSMauro Carvalho Chehab Summary 1452f476c6edSMauro Carvalho Chehab Flush the name cache entirely. 1453f476c6edSMauro Carvalho Chehab 1454f476c6edSMauro Carvalho Chehab Description 1455f476c6edSMauro Carvalho Chehab Venus issues this call upon startup and when it dies. This 1456f476c6edSMauro Carvalho Chehab is to prevent stale cache information being held. Some operating 1457f476c6edSMauro Carvalho Chehab systems allow the kernel name cache to be switched off dynamically. 1458f476c6edSMauro Carvalho Chehab When this is done, this downcall is made. 1459f476c6edSMauro Carvalho Chehab 1460f476c6edSMauro Carvalho Chehab 1461f476c6edSMauro Carvalho Chehab5.3. PURGEUSER 1462f476c6edSMauro Carvalho Chehab--------------- 1463f476c6edSMauro Carvalho Chehab 1464f476c6edSMauro Carvalho Chehab 1465f476c6edSMauro Carvalho Chehab Arguments 1466f476c6edSMauro Carvalho Chehab :: 1467f476c6edSMauro Carvalho Chehab 1468f476c6edSMauro Carvalho Chehab struct cfs_purgeuser_out {/* CFS_PURGEUSER is a venus->kernel call */ 1469f476c6edSMauro Carvalho Chehab struct CodaCred cred; 1470f476c6edSMauro Carvalho Chehab } cfs_purgeuser; 1471f476c6edSMauro Carvalho Chehab 1472f476c6edSMauro Carvalho Chehab 1473f476c6edSMauro Carvalho Chehab 1474f476c6edSMauro Carvalho Chehab Description 1475f476c6edSMauro Carvalho Chehab Remove all entries in the cache carrying the Cred. This 1476f476c6edSMauro Carvalho Chehab call is issued when tokens for a user expire or are flushed. 1477f476c6edSMauro Carvalho Chehab 1478f476c6edSMauro Carvalho Chehab 1479f476c6edSMauro Carvalho Chehab5.4. ZAPFILE 1480f476c6edSMauro Carvalho Chehab------------- 1481f476c6edSMauro Carvalho Chehab 1482f476c6edSMauro Carvalho Chehab 1483f476c6edSMauro Carvalho Chehab Arguments 1484f476c6edSMauro Carvalho Chehab :: 1485f476c6edSMauro Carvalho Chehab 1486f476c6edSMauro Carvalho Chehab struct cfs_zapfile_out { /* CFS_ZAPFILE is a venus->kernel call */ 1487f476c6edSMauro Carvalho Chehab ViceFid CodaFid; 1488f476c6edSMauro Carvalho Chehab } cfs_zapfile; 1489f476c6edSMauro Carvalho Chehab 1490f476c6edSMauro Carvalho Chehab 1491f476c6edSMauro Carvalho Chehab 1492f476c6edSMauro Carvalho Chehab Description 1493f476c6edSMauro Carvalho Chehab Remove all entries which have the (dir vnode, name) pair. 1494f476c6edSMauro Carvalho Chehab This is issued as a result of an invalidation of cached attributes of 1495f476c6edSMauro Carvalho Chehab a vnode. 1496f476c6edSMauro Carvalho Chehab 1497f476c6edSMauro Carvalho Chehab .. Note:: 1498f476c6edSMauro Carvalho Chehab 1499f476c6edSMauro Carvalho Chehab Call is not named correctly in NetBSD and Mach. The minicache 1500f476c6edSMauro Carvalho Chehab zapfile routine takes different arguments. Linux does not implement 1501f476c6edSMauro Carvalho Chehab the invalidation of attributes correctly. 1502f476c6edSMauro Carvalho Chehab 1503f476c6edSMauro Carvalho Chehab 1504f476c6edSMauro Carvalho Chehab 1505f476c6edSMauro Carvalho Chehab5.5. ZAPDIR 1506f476c6edSMauro Carvalho Chehab------------ 1507f476c6edSMauro Carvalho Chehab 1508f476c6edSMauro Carvalho Chehab 1509f476c6edSMauro Carvalho Chehab Arguments 1510f476c6edSMauro Carvalho Chehab :: 1511f476c6edSMauro Carvalho Chehab 1512f476c6edSMauro Carvalho Chehab struct cfs_zapdir_out { /* CFS_ZAPDIR is a venus->kernel call */ 1513f476c6edSMauro Carvalho Chehab ViceFid CodaFid; 1514f476c6edSMauro Carvalho Chehab } cfs_zapdir; 1515f476c6edSMauro Carvalho Chehab 1516f476c6edSMauro Carvalho Chehab 1517f476c6edSMauro Carvalho Chehab 1518f476c6edSMauro Carvalho Chehab Description 1519f476c6edSMauro Carvalho Chehab Remove all entries in the cache lying in a directory 1520f476c6edSMauro Carvalho Chehab CodaFid, and all children of this directory. This call is issued when 1521f476c6edSMauro Carvalho Chehab Venus receives a callback on the directory. 1522f476c6edSMauro Carvalho Chehab 1523f476c6edSMauro Carvalho Chehab 1524f476c6edSMauro Carvalho Chehab5.6. ZAPVNODE 1525f476c6edSMauro Carvalho Chehab-------------- 1526f476c6edSMauro Carvalho Chehab 1527f476c6edSMauro Carvalho Chehab 1528f476c6edSMauro Carvalho Chehab 1529f476c6edSMauro Carvalho Chehab Arguments 1530f476c6edSMauro Carvalho Chehab :: 1531f476c6edSMauro Carvalho Chehab 1532f476c6edSMauro Carvalho Chehab struct cfs_zapvnode_out { /* CFS_ZAPVNODE is a venus->kernel call */ 1533f476c6edSMauro Carvalho Chehab struct CodaCred cred; 1534f476c6edSMauro Carvalho Chehab ViceFid VFid; 1535f476c6edSMauro Carvalho Chehab } cfs_zapvnode; 1536f476c6edSMauro Carvalho Chehab 1537f476c6edSMauro Carvalho Chehab 1538f476c6edSMauro Carvalho Chehab 1539f476c6edSMauro Carvalho Chehab Description 1540f476c6edSMauro Carvalho Chehab Remove all entries in the cache carrying the cred and VFid 1541f476c6edSMauro Carvalho Chehab as in the arguments. This downcall is probably never issued. 1542f476c6edSMauro Carvalho Chehab 1543f476c6edSMauro Carvalho Chehab 1544f476c6edSMauro Carvalho Chehab5.7. PURGEFID 1545f476c6edSMauro Carvalho Chehab-------------- 1546f476c6edSMauro Carvalho Chehab 1547f476c6edSMauro Carvalho Chehab 1548f476c6edSMauro Carvalho Chehab Arguments 1549f476c6edSMauro Carvalho Chehab :: 1550f476c6edSMauro Carvalho Chehab 1551f476c6edSMauro Carvalho Chehab struct cfs_purgefid_out { /* CFS_PURGEFID is a venus->kernel call */ 1552f476c6edSMauro Carvalho Chehab ViceFid CodaFid; 1553f476c6edSMauro Carvalho Chehab } cfs_purgefid; 1554f476c6edSMauro Carvalho Chehab 1555f476c6edSMauro Carvalho Chehab 1556f476c6edSMauro Carvalho Chehab 1557f476c6edSMauro Carvalho Chehab Description 1558f476c6edSMauro Carvalho Chehab Flush the attribute for the file. If it is a dir (odd 1559f476c6edSMauro Carvalho Chehab vnode), purge its children from the namecache and remove the file from the 1560f476c6edSMauro Carvalho Chehab namecache. 1561f476c6edSMauro Carvalho Chehab 1562f476c6edSMauro Carvalho Chehab 1563f476c6edSMauro Carvalho Chehab 1564f476c6edSMauro Carvalho Chehab5.8. REPLACE 1565f476c6edSMauro Carvalho Chehab------------- 1566f476c6edSMauro Carvalho Chehab 1567f476c6edSMauro Carvalho Chehab 1568f476c6edSMauro Carvalho Chehab Summary 1569f476c6edSMauro Carvalho Chehab Replace the Fid's for a collection of names. 1570f476c6edSMauro Carvalho Chehab 1571f476c6edSMauro Carvalho Chehab Arguments 1572f476c6edSMauro Carvalho Chehab :: 1573f476c6edSMauro Carvalho Chehab 1574f476c6edSMauro Carvalho Chehab struct cfs_replace_out { /* cfs_replace is a venus->kernel call */ 1575f476c6edSMauro Carvalho Chehab ViceFid NewFid; 1576f476c6edSMauro Carvalho Chehab ViceFid OldFid; 1577f476c6edSMauro Carvalho Chehab } cfs_replace; 1578f476c6edSMauro Carvalho Chehab 1579f476c6edSMauro Carvalho Chehab 1580f476c6edSMauro Carvalho Chehab 1581f476c6edSMauro Carvalho Chehab Description 1582f476c6edSMauro Carvalho Chehab This routine replaces a ViceFid in the name cache with 1583f476c6edSMauro Carvalho Chehab another. It is added to allow Venus during reintegration to replace 1584f476c6edSMauro Carvalho Chehab locally allocated temp fids while disconnected with global fids even 1585f476c6edSMauro Carvalho Chehab when the reference counts on those fids are not zero. 1586f476c6edSMauro Carvalho Chehab 1587f476c6edSMauro Carvalho Chehab 1588f476c6edSMauro Carvalho Chehab6. Initialization and cleanup 1589f476c6edSMauro Carvalho Chehab============================== 1590f476c6edSMauro Carvalho Chehab 1591f476c6edSMauro Carvalho Chehab 1592f476c6edSMauro Carvalho Chehab This section gives brief hints as to desirable features for the Coda 1593f476c6edSMauro Carvalho Chehab FS Driver at startup and upon shutdown or Venus failures. Before 1594f476c6edSMauro Carvalho Chehab entering the discussion it is useful to repeat that the Coda FS Driver 1595f476c6edSMauro Carvalho Chehab maintains the following data: 1596f476c6edSMauro Carvalho Chehab 1597f476c6edSMauro Carvalho Chehab 1598f476c6edSMauro Carvalho Chehab 1. message queues 1599f476c6edSMauro Carvalho Chehab 1600f476c6edSMauro Carvalho Chehab 2. cnodes 1601f476c6edSMauro Carvalho Chehab 1602f476c6edSMauro Carvalho Chehab 3. name cache entries 1603f476c6edSMauro Carvalho Chehab 1604f476c6edSMauro Carvalho Chehab The name cache entries are entirely private to the driver, so they 1605f476c6edSMauro Carvalho Chehab can easily be manipulated. The message queues will generally have 1606f476c6edSMauro Carvalho Chehab clear points of initialization and destruction. The cnodes are 1607f476c6edSMauro Carvalho Chehab much more delicate. User processes hold reference counts in Coda 1608f476c6edSMauro Carvalho Chehab filesystems and it can be difficult to clean up the cnodes. 1609f476c6edSMauro Carvalho Chehab 1610f476c6edSMauro Carvalho Chehab It can expect requests through: 1611f476c6edSMauro Carvalho Chehab 1612f476c6edSMauro Carvalho Chehab 1. the message subsystem 1613f476c6edSMauro Carvalho Chehab 1614f476c6edSMauro Carvalho Chehab 2. the VFS layer 1615f476c6edSMauro Carvalho Chehab 1616f476c6edSMauro Carvalho Chehab 3. pioctl interface 1617f476c6edSMauro Carvalho Chehab 1618f476c6edSMauro Carvalho Chehab Currently the pioctl passes through the VFS for Coda so we can 1619f476c6edSMauro Carvalho Chehab treat these similarly. 1620f476c6edSMauro Carvalho Chehab 1621f476c6edSMauro Carvalho Chehab 1622f476c6edSMauro Carvalho Chehab6.1. Requirements 1623f476c6edSMauro Carvalho Chehab------------------ 1624f476c6edSMauro Carvalho Chehab 1625f476c6edSMauro Carvalho Chehab 1626f476c6edSMauro Carvalho Chehab The following requirements should be accommodated: 1627f476c6edSMauro Carvalho Chehab 1628f476c6edSMauro Carvalho Chehab 1. The message queues should have open and close routines. On Unix 1629f476c6edSMauro Carvalho Chehab the opening of the character devices are such routines. 1630f476c6edSMauro Carvalho Chehab 1631f476c6edSMauro Carvalho Chehab - Before opening, no messages can be placed. 1632f476c6edSMauro Carvalho Chehab 1633f476c6edSMauro Carvalho Chehab - Opening will remove any old messages still pending. 1634f476c6edSMauro Carvalho Chehab 1635f476c6edSMauro Carvalho Chehab - Close will notify any sleeping processes that their upcall cannot 1636f476c6edSMauro Carvalho Chehab be completed. 1637f476c6edSMauro Carvalho Chehab 1638f476c6edSMauro Carvalho Chehab - Close will free all memory allocated by the message queues. 1639f476c6edSMauro Carvalho Chehab 1640f476c6edSMauro Carvalho Chehab 1641f476c6edSMauro Carvalho Chehab 2. At open the namecache shall be initialized to empty state. 1642f476c6edSMauro Carvalho Chehab 1643f476c6edSMauro Carvalho Chehab 3. Before the message queues are open, all VFS operations will fail. 1644f476c6edSMauro Carvalho Chehab Fortunately this can be achieved by making sure than mounting the 1645f476c6edSMauro Carvalho Chehab Coda filesystem cannot succeed before opening. 1646f476c6edSMauro Carvalho Chehab 1647f476c6edSMauro Carvalho Chehab 4. After closing of the queues, no VFS operations can succeed. Here 1648f476c6edSMauro Carvalho Chehab one needs to be careful, since a few operations (lookup, 1649f476c6edSMauro Carvalho Chehab read/write, readdir) can proceed without upcalls. These must be 1650f476c6edSMauro Carvalho Chehab explicitly blocked. 1651f476c6edSMauro Carvalho Chehab 1652f476c6edSMauro Carvalho Chehab 5. Upon closing the namecache shall be flushed and disabled. 1653f476c6edSMauro Carvalho Chehab 1654f476c6edSMauro Carvalho Chehab 6. All memory held by cnodes can be freed without relying on upcalls. 1655f476c6edSMauro Carvalho Chehab 1656f476c6edSMauro Carvalho Chehab 7. Unmounting the file system can be done without relying on upcalls. 1657f476c6edSMauro Carvalho Chehab 1658f476c6edSMauro Carvalho Chehab 8. Mounting the Coda filesystem should fail gracefully if Venus cannot 1659f476c6edSMauro Carvalho Chehab get the rootfid or the attributes of the rootfid. The latter is 1660f476c6edSMauro Carvalho Chehab best implemented by Venus fetching these objects before attempting 1661f476c6edSMauro Carvalho Chehab to mount. 1662f476c6edSMauro Carvalho Chehab 1663f476c6edSMauro Carvalho Chehab .. Note:: 1664f476c6edSMauro Carvalho Chehab 1665f476c6edSMauro Carvalho Chehab NetBSD in particular but also Linux have not implemented the 1666f476c6edSMauro Carvalho Chehab above requirements fully. For smooth operation this needs to be 1667f476c6edSMauro Carvalho Chehab corrected. 1668f476c6edSMauro Carvalho Chehab 1669f476c6edSMauro Carvalho Chehab 1670f476c6edSMauro Carvalho Chehab 1671