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