]>
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 | |
c6e03961 | 424 | they are set for the calling process. The vuid_t and vgid_t are 32 bit |
1da177e4 LT |
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 { | |
c6e03961 | 431 | vuid_t cr_uid, cr_euid, cr_suid, cr_fsuid; /* Real, effective, set, fs uid */ |
1da177e4 LT |
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 | ||
5e7c31df JH |
484 | struct coda_timespec { |
485 | int64_t tv_sec; /* seconds */ | |
6ced9aa7 AB |
486 | long tv_nsec; /* nanoseconds */ |
487 | }; | |
1da177e4 LT |
488 | |
489 | struct coda_vattr { | |
490 | enum coda_vtype va_type; /* vnode type (for create) */ | |
491 | u_short va_mode; /* files access mode and type */ | |
492 | short va_nlink; /* number of references to file */ | |
493 | vuid_t va_uid; /* owner user id */ | |
494 | vgid_t va_gid; /* owner group id */ | |
495 | long va_fsid; /* file system id (dev for now) */ | |
496 | long va_fileid; /* file id */ | |
497 | u_quad_t va_size; /* file size in bytes */ | |
498 | long va_blocksize; /* blocksize preferred for i/o */ | |
5e7c31df JH |
499 | struct coda_timespec va_atime; /* time of last access */ |
500 | struct coda_timespec va_mtime; /* time of last modification */ | |
501 | struct coda_timespec va_ctime; /* time file changed */ | |
1da177e4 LT |
502 | u_long va_gen; /* generation number of file */ |
503 | u_long va_flags; /* flags defined for file */ | |
504 | dev_t va_rdev; /* device special file represents */ | |
505 | u_quad_t va_bytes; /* bytes of disk space held by file */ | |
506 | u_quad_t va_filerev; /* file modification number */ | |
507 | u_int va_vaflags; /* operations flags, see below */ | |
508 | long va_spare; /* remain quad aligned */ | |
509 | }; | |
510 | ||
511 | ||
512 | ||
513 | ||
514 | 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 | |
515 | ||
516 | ||
517 | Coda specific requests can be made by application through the pioctl | |
518 | interface. The pioctl is implemented as an ordinary ioctl on a | |
519 | fictitious file /coda/.CONTROL. The pioctl call opens this file, gets | |
520 | a file handle and makes the ioctl call. Finally it closes the file. | |
521 | ||
522 | The kernel involvement in this is limited to providing the facility to | |
523 | open and close and pass the ioctl message _\ba_\bn_\bd to verify that a path in | |
524 | the pioctl data buffers is a file in a Coda filesystem. | |
525 | ||
526 | The kernel is handed a data packet of the form: | |
527 | ||
528 | struct { | |
529 | const char *path; | |
530 | struct ViceIoctl vidata; | |
531 | int follow; | |
532 | } data; | |
533 | ||
534 | ||
535 | ||
536 | where | |
537 | ||
538 | ||
539 | struct ViceIoctl { | |
540 | caddr_t in, out; /* Data to be transferred in, or out */ | |
541 | short in_size; /* Size of input buffer <= 2K */ | |
542 | short out_size; /* Maximum size of output buffer, <= 2K */ | |
543 | }; | |
544 | ||
545 | ||
546 | ||
547 | The path must be a Coda file, otherwise the ioctl upcall will not be | |
548 | made. | |
549 | ||
550 | N\bNO\bOT\bTE\bE The data structures and code are a mess. We need to clean this | |
551 | up. | |
552 | ||
553 | We now proceed to document the individual calls: | |
554 | ||
555 | 0wpage | |
556 | ||
557 | 4\b4.\b.3\b3.\b. r\bro\boo\bot\bt | |
558 | ||
559 | ||
560 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
561 | ||
562 | i\bin\bn empty | |
563 | ||
564 | o\bou\but\bt | |
565 | ||
566 | struct cfs_root_out { | |
567 | ViceFid VFid; | |
568 | } cfs_root; | |
569 | ||
570 | ||
571 | ||
572 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn This call is made to Venus during the initialization of | |
573 | the Coda filesystem. If the result is zero, the cfs_root structure | |
574 | contains the ViceFid of the root of the Coda filesystem. If a non-zero | |
575 | result is generated, its value is a platform dependent error code | |
576 | indicating the difficulty Venus encountered in locating the root of | |
577 | the Coda filesystem. | |
578 | ||
579 | 0wpage | |
580 | ||
581 | 4\b4.\b.4\b4.\b. l\blo\boo\bok\bku\bup\bp | |
582 | ||
583 | ||
584 | S\bSu\bum\bmm\bma\bar\bry\by Find the ViceFid and type of an object in a directory if it | |
585 | exists. | |
586 | ||
587 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
588 | ||
589 | i\bin\bn | |
590 | ||
591 | struct cfs_lookup_in { | |
592 | ViceFid VFid; | |
593 | char *name; /* Place holder for data. */ | |
594 | } cfs_lookup; | |
595 | ||
596 | ||
597 | ||
598 | o\bou\but\bt | |
599 | ||
600 | struct cfs_lookup_out { | |
601 | ViceFid VFid; | |
602 | int vtype; | |
603 | } cfs_lookup; | |
604 | ||
605 | ||
606 | ||
607 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn This call is made to determine the ViceFid and filetype of | |
608 | a directory entry. The directory entry requested carries name name | |
609 | and Venus will search the directory identified by cfs_lookup_in.VFid. | |
610 | The result may indicate that the name does not exist, or that | |
611 | difficulty was encountered in finding it (e.g. due to disconnection). | |
612 | If the result is zero, the field cfs_lookup_out.VFid contains the | |
613 | targets ViceFid and cfs_lookup_out.vtype the coda_vtype giving the | |
614 | type of object the name designates. | |
615 | ||
616 | The name of the object is an 8 bit character string of maximum length | |
617 | CFS_MAXNAMLEN, currently set to 256 (including a 0 terminator.) | |
618 | ||
619 | It is extremely important to realize that Venus bitwise ors the field | |
620 | cfs_lookup.vtype with CFS_NOCACHE to indicate that the object should | |
621 | not be put in the kernel name cache. | |
622 | ||
623 | N\bNO\bOT\bTE\bE The type of the vtype is currently wrong. It should be | |
624 | coda_vtype. Linux does not take note of CFS_NOCACHE. It should. | |
625 | ||
626 | 0wpage | |
627 | ||
628 | 4\b4.\b.5\b5.\b. g\bge\bet\bta\bat\btt\btr\br | |
629 | ||
630 | ||
631 | S\bSu\bum\bmm\bma\bar\bry\by Get the attributes of a file. | |
632 | ||
633 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
634 | ||
635 | i\bin\bn | |
636 | ||
637 | struct cfs_getattr_in { | |
638 | ViceFid VFid; | |
639 | struct coda_vattr attr; /* XXXXX */ | |
640 | } cfs_getattr; | |
641 | ||
642 | ||
643 | ||
644 | o\bou\but\bt | |
645 | ||
646 | struct cfs_getattr_out { | |
647 | struct coda_vattr attr; | |
648 | } cfs_getattr; | |
649 | ||
650 | ||
651 | ||
652 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn This call returns the attributes of the file identified by | |
653 | fid. | |
654 | ||
655 | E\bEr\brr\bro\bor\brs\bs Errors can occur if the object with fid does not exist, is | |
656 | unaccessible or if the caller does not have permission to fetch | |
657 | attributes. | |
658 | ||
659 | N\bNo\bot\bte\be Many kernel FS drivers (Linux, NT and Windows 95) need to acquire | |
660 | the attributes as well as the Fid for the instantiation of an internal | |
661 | "inode" or "FileHandle". A significant improvement in performance on | |
662 | such systems could be made by combining the _\bl_\bo_\bo_\bk_\bu_\bp and _\bg_\be_\bt_\ba_\bt_\bt_\br calls | |
663 | both at the Venus/kernel interaction level and at the RPC level. | |
664 | ||
665 | The vattr structure included in the input arguments is superfluous and | |
666 | should be removed. | |
667 | ||
668 | 0wpage | |
669 | ||
670 | 4\b4.\b.6\b6.\b. s\bse\bet\bta\bat\btt\btr\br | |
671 | ||
672 | ||
673 | S\bSu\bum\bmm\bma\bar\bry\by Set the attributes of a file. | |
674 | ||
675 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
676 | ||
677 | i\bin\bn | |
678 | ||
679 | struct cfs_setattr_in { | |
680 | ViceFid VFid; | |
681 | struct coda_vattr attr; | |
682 | } cfs_setattr; | |
683 | ||
684 | ||
685 | ||
686 | ||
687 | o\bou\but\bt | |
688 | empty | |
689 | ||
690 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn The structure attr is filled with attributes to be changed | |
691 | in BSD style. Attributes not to be changed are set to -1, apart from | |
692 | vtype which is set to VNON. Other are set to the value to be assigned. | |
693 | The only attributes which the FS driver may request to change are the | |
694 | mode, owner, groupid, atime, mtime and ctime. The return value | |
695 | indicates success or failure. | |
696 | ||
697 | E\bEr\brr\bro\bor\brs\bs A variety of errors can occur. The object may not exist, may | |
698 | be inaccessible, or permission may not be granted by Venus. | |
699 | ||
700 | 0wpage | |
701 | ||
702 | 4\b4.\b.7\b7.\b. a\bac\bcc\bce\bes\bss\bs | |
703 | ||
704 | ||
705 | S\bSu\bum\bmm\bma\bar\bry\by | |
706 | ||
707 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
708 | ||
709 | i\bin\bn | |
710 | ||
711 | struct cfs_access_in { | |
712 | ViceFid VFid; | |
713 | int flags; | |
714 | } cfs_access; | |
715 | ||
716 | ||
717 | ||
718 | o\bou\but\bt | |
719 | empty | |
720 | ||
721 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn Verify if access to the object identified by VFid for | |
722 | operations described by flags is permitted. The result indicates if | |
723 | access will be granted. It is important to remember that Coda uses | |
724 | ACLs to enforce protection and that ultimately the servers, not the | |
725 | clients enforce the security of the system. The result of this call | |
726 | will depend on whether a _\bt_\bo_\bk_\be_\bn is held by the user. | |
727 | ||
728 | E\bEr\brr\bro\bor\brs\bs The object may not exist, or the ACL describing the protection | |
729 | may not be accessible. | |
730 | ||
731 | 0wpage | |
732 | ||
733 | 4\b4.\b.8\b8.\b. c\bcr\bre\bea\bat\bte\be | |
734 | ||
735 | ||
736 | S\bSu\bum\bmm\bma\bar\bry\by Invoked to create a file | |
737 | ||
738 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
739 | ||
740 | i\bin\bn | |
741 | ||
742 | struct cfs_create_in { | |
743 | ViceFid VFid; | |
744 | struct coda_vattr attr; | |
745 | int excl; | |
746 | int mode; | |
747 | char *name; /* Place holder for data. */ | |
748 | } cfs_create; | |
749 | ||
750 | ||
751 | ||
752 | ||
753 | o\bou\but\bt | |
754 | ||
755 | struct cfs_create_out { | |
756 | ViceFid VFid; | |
757 | struct coda_vattr attr; | |
758 | } cfs_create; | |
759 | ||
760 | ||
761 | ||
762 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn This upcall is invoked to request creation of a file. | |
763 | The file will be created in the directory identified by VFid, its name | |
764 | will be name, and the mode will be mode. If excl is set an error will | |
765 | be returned if the file already exists. If the size field in attr is | |
766 | set to zero the file will be truncated. The uid and gid of the file | |
767 | are set by converting the CodaCred to a uid using a macro CRTOUID | |
768 | (this macro is platform dependent). Upon success the VFid and | |
769 | attributes of the file are returned. The Coda FS Driver will normally | |
770 | instantiate a vnode, inode or file handle at kernel level for the new | |
771 | object. | |
772 | ||
773 | ||
774 | E\bEr\brr\bro\bor\brs\bs A variety of errors can occur. Permissions may be insufficient. | |
775 | If the object exists and is not a file the error EISDIR is returned | |
776 | under Unix. | |
777 | ||
778 | N\bNO\bOT\bTE\bE The packing of parameters is very inefficient and appears to | |
779 | indicate confusion between the system call creat and the VFS operation | |
780 | create. The VFS operation create is only called to create new objects. | |
781 | This create call differs from the Unix one in that it is not invoked | |
782 | to return a file descriptor. The truncate and exclusive options, | |
783 | together with the mode, could simply be part of the mode as it is | |
784 | under Unix. There should be no flags argument; this is used in open | |
785 | (2) to return a file descriptor for READ or WRITE mode. | |
786 | ||
787 | The attributes of the directory should be returned too, since the size | |
788 | and mtime changed. | |
789 | ||
790 | 0wpage | |
791 | ||
792 | 4\b4.\b.9\b9.\b. m\bmk\bkd\bdi\bir\br | |
793 | ||
794 | ||
795 | S\bSu\bum\bmm\bma\bar\bry\by Create a new directory. | |
796 | ||
797 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
798 | ||
799 | i\bin\bn | |
800 | ||
801 | struct cfs_mkdir_in { | |
802 | ViceFid VFid; | |
803 | struct coda_vattr attr; | |
804 | char *name; /* Place holder for data. */ | |
805 | } cfs_mkdir; | |
806 | ||
807 | ||
808 | ||
809 | o\bou\but\bt | |
810 | ||
811 | struct cfs_mkdir_out { | |
812 | ViceFid VFid; | |
813 | struct coda_vattr attr; | |
814 | } cfs_mkdir; | |
815 | ||
816 | ||
817 | ||
818 | ||
819 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn This call is similar to create but creates a directory. | |
820 | Only the mode field in the input parameters is used for creation. | |
821 | Upon successful creation, the attr returned contains the attributes of | |
822 | the new directory. | |
823 | ||
824 | E\bEr\brr\bro\bor\brs\bs As for create. | |
825 | ||
826 | N\bNO\bOT\bTE\bE The input parameter should be changed to mode instead of | |
827 | attributes. | |
828 | ||
829 | The attributes of the parent should be returned since the size and | |
830 | mtime changes. | |
831 | ||
832 | 0wpage | |
833 | ||
834 | 4\b4.\b.1\b10\b0.\b. l\bli\bin\bnk\bk | |
835 | ||
836 | ||
837 | S\bSu\bum\bmm\bma\bar\bry\by Create a link to an existing file. | |
838 | ||
839 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
840 | ||
841 | i\bin\bn | |
842 | ||
843 | struct cfs_link_in { | |
844 | ViceFid sourceFid; /* cnode to link *to* */ | |
845 | ViceFid destFid; /* Directory in which to place link */ | |
846 | char *tname; /* Place holder for data. */ | |
847 | } cfs_link; | |
848 | ||
849 | ||
850 | ||
851 | o\bou\but\bt | |
852 | empty | |
853 | ||
854 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn This call creates a link to the sourceFid in the directory | |
855 | identified by destFid with name tname. The source must reside in the | |
856 | target's parent, i.e. the source must be have parent destFid, i.e. Coda | |
857 | does not support cross directory hard links. Only the return value is | |
858 | relevant. It indicates success or the type of failure. | |
859 | ||
860 | E\bEr\brr\bro\bor\brs\bs The usual errors can occur.0wpage | |
861 | ||
862 | 4\b4.\b.1\b11\b1.\b. s\bsy\bym\bml\bli\bin\bnk\bk | |
863 | ||
864 | ||
865 | S\bSu\bum\bmm\bma\bar\bry\by create a symbolic link | |
866 | ||
867 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
868 | ||
869 | i\bin\bn | |
870 | ||
871 | struct cfs_symlink_in { | |
872 | ViceFid VFid; /* Directory to put symlink in */ | |
873 | char *srcname; | |
874 | struct coda_vattr attr; | |
875 | char *tname; | |
876 | } cfs_symlink; | |
877 | ||
878 | ||
879 | ||
880 | o\bou\but\bt | |
881 | none | |
882 | ||
883 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn Create a symbolic link. The link is to be placed in the | |
884 | directory identified by VFid and named tname. It should point to the | |
885 | pathname srcname. The attributes of the newly created object are to | |
886 | be set to attr. | |
887 | ||
888 | E\bEr\brr\bro\bor\brs\bs | |
889 | ||
890 | N\bNO\bOT\bTE\bE The attributes of the target directory should be returned since | |
891 | its size changed. | |
892 | ||
893 | 0wpage | |
894 | ||
895 | 4\b4.\b.1\b12\b2.\b. r\bre\bem\bmo\bov\bve\be | |
896 | ||
897 | ||
898 | S\bSu\bum\bmm\bma\bar\bry\by Remove a file | |
899 | ||
900 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
901 | ||
902 | i\bin\bn | |
903 | ||
904 | struct cfs_remove_in { | |
905 | ViceFid VFid; | |
906 | char *name; /* Place holder for data. */ | |
907 | } cfs_remove; | |
908 | ||
909 | ||
910 | ||
911 | o\bou\but\bt | |
912 | none | |
913 | ||
914 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn Remove file named cfs_remove_in.name in directory | |
915 | identified by VFid. | |
916 | ||
917 | E\bEr\brr\bro\bor\brs\bs | |
918 | ||
919 | N\bNO\bOT\bTE\bE The attributes of the directory should be returned since its | |
920 | mtime and size may change. | |
921 | ||
922 | 0wpage | |
923 | ||
924 | 4\b4.\b.1\b13\b3.\b. r\brm\bmd\bdi\bir\br | |
925 | ||
926 | ||
927 | S\bSu\bum\bmm\bma\bar\bry\by Remove a directory | |
928 | ||
929 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
930 | ||
931 | i\bin\bn | |
932 | ||
933 | struct cfs_rmdir_in { | |
934 | ViceFid VFid; | |
935 | char *name; /* Place holder for data. */ | |
936 | } cfs_rmdir; | |
937 | ||
938 | ||
939 | ||
940 | o\bou\but\bt | |
941 | none | |
942 | ||
943 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn Remove the directory with name name from the directory | |
944 | identified by VFid. | |
945 | ||
946 | E\bEr\brr\bro\bor\brs\bs | |
947 | ||
948 | N\bNO\bOT\bTE\bE The attributes of the parent directory should be returned since | |
949 | its mtime and size may change. | |
950 | ||
951 | 0wpage | |
952 | ||
953 | 4\b4.\b.1\b14\b4.\b. r\bre\bea\bad\bdl\bli\bin\bnk\bk | |
954 | ||
955 | ||
956 | S\bSu\bum\bmm\bma\bar\bry\by Read the value of a symbolic link. | |
957 | ||
958 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
959 | ||
960 | i\bin\bn | |
961 | ||
962 | struct cfs_readlink_in { | |
963 | ViceFid VFid; | |
964 | } cfs_readlink; | |
965 | ||
966 | ||
967 | ||
968 | o\bou\but\bt | |
969 | ||
970 | struct cfs_readlink_out { | |
971 | int count; | |
972 | caddr_t data; /* Place holder for data. */ | |
973 | } cfs_readlink; | |
974 | ||
975 | ||
976 | ||
977 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn This routine reads the contents of symbolic link | |
978 | identified by VFid into the buffer data. The buffer data must be able | |
979 | to hold any name up to CFS_MAXNAMLEN (PATH or NAM??). | |
980 | ||
981 | E\bEr\brr\bro\bor\brs\bs No unusual errors. | |
982 | ||
983 | 0wpage | |
984 | ||
985 | 4\b4.\b.1\b15\b5.\b. o\bop\bpe\ben\bn | |
986 | ||
987 | ||
988 | S\bSu\bum\bmm\bma\bar\bry\by Open a file. | |
989 | ||
990 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
991 | ||
992 | i\bin\bn | |
993 | ||
994 | struct cfs_open_in { | |
995 | ViceFid VFid; | |
996 | int flags; | |
997 | } cfs_open; | |
998 | ||
999 | ||
1000 | ||
1001 | o\bou\but\bt | |
1002 | ||
1003 | struct cfs_open_out { | |
1004 | dev_t dev; | |
1005 | ino_t inode; | |
1006 | } cfs_open; | |
1007 | ||
1008 | ||
1009 | ||
1010 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn This request asks Venus to place the file identified by | |
1011 | VFid in its cache and to note that the calling process wishes to open | |
1012 | it with flags as in open(2). The return value to the kernel differs | |
1013 | for Unix and Windows systems. For Unix systems the Coda FS Driver is | |
1014 | informed of the device and inode number of the container file in the | |
1015 | fields dev and inode. For Windows the path of the container file is | |
1016 | returned to the kernel. | |
1017 | E\bEr\brr\bro\bor\brs\bs | |
1018 | ||
1019 | N\bNO\bOT\bTE\bE Currently the cfs_open_out structure is not properly adapted to | |
1020 | deal with the Windows case. It might be best to implement two | |
1021 | upcalls, one to open aiming at a container file name, the other at a | |
1022 | container file inode. | |
1023 | ||
1024 | 0wpage | |
1025 | ||
1026 | 4\b4.\b.1\b16\b6.\b. c\bcl\blo\bos\bse\be | |
1027 | ||
1028 | ||
1029 | S\bSu\bum\bmm\bma\bar\bry\by Close a file, update it on the servers. | |
1030 | ||
1031 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
1032 | ||
1033 | i\bin\bn | |
1034 | ||
1035 | struct cfs_close_in { | |
1036 | ViceFid VFid; | |
1037 | int flags; | |
1038 | } cfs_close; | |
1039 | ||
1040 | ||
1041 | ||
1042 | o\bou\but\bt | |
1043 | none | |
1044 | ||
1045 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn Close the file identified by VFid. | |
1046 | ||
1047 | E\bEr\brr\bro\bor\brs\bs | |
1048 | ||
1049 | N\bNO\bOT\bTE\bE The flags argument is bogus and not used. However, Venus' code | |
1050 | has room to deal with an execp input field, probably this field should | |
1051 | be used to inform Venus that the file was closed but is still memory | |
1052 | mapped for execution. There are comments about fetching versus not | |
1053 | fetching the data in Venus vproc_vfscalls. This seems silly. If a | |
1054 | file is being closed, the data in the container file is to be the new | |
1055 | data. Here again the execp flag might be in play to create confusion: | |
1056 | currently Venus might think a file can be flushed from the cache when | |
1057 | it is still memory mapped. This needs to be understood. | |
1058 | ||
1059 | 0wpage | |
1060 | ||
1061 | 4\b4.\b.1\b17\b7.\b. i\bio\boc\bct\btl\bl | |
1062 | ||
1063 | ||
1064 | S\bSu\bum\bmm\bma\bar\bry\by Do an ioctl on a file. This includes the pioctl interface. | |
1065 | ||
1066 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
1067 | ||
1068 | i\bin\bn | |
1069 | ||
1070 | struct cfs_ioctl_in { | |
1071 | ViceFid VFid; | |
1072 | int cmd; | |
1073 | int len; | |
1074 | int rwflag; | |
1075 | char *data; /* Place holder for data. */ | |
1076 | } cfs_ioctl; | |
1077 | ||
1078 | ||
1079 | ||
1080 | o\bou\but\bt | |
1081 | ||
1082 | ||
1083 | struct cfs_ioctl_out { | |
1084 | int len; | |
1085 | caddr_t data; /* Place holder for data. */ | |
1086 | } cfs_ioctl; | |
1087 | ||
1088 | ||
1089 | ||
1090 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn Do an ioctl operation on a file. The command, len and | |
1091 | data arguments are filled as usual. flags is not used by Venus. | |
1092 | ||
1093 | E\bEr\brr\bro\bor\brs\bs | |
1094 | ||
1095 | N\bNO\bOT\bTE\bE Another bogus parameter. flags is not used. What is the | |
1096 | business about PREFETCHING in the Venus code? | |
1097 | ||
1098 | ||
1099 | 0wpage | |
1100 | ||
1101 | 4\b4.\b.1\b18\b8.\b. r\bre\ben\bna\bam\bme\be | |
1102 | ||
1103 | ||
1104 | S\bSu\bum\bmm\bma\bar\bry\by Rename a fid. | |
1105 | ||
1106 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
1107 | ||
1108 | i\bin\bn | |
1109 | ||
1110 | struct cfs_rename_in { | |
1111 | ViceFid sourceFid; | |
1112 | char *srcname; | |
1113 | ViceFid destFid; | |
1114 | char *destname; | |
1115 | } cfs_rename; | |
1116 | ||
1117 | ||
1118 | ||
1119 | o\bou\but\bt | |
1120 | none | |
1121 | ||
1122 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn Rename the object with name srcname in directory | |
1123 | sourceFid to destname in destFid. It is important that the names | |
1124 | srcname and destname are 0 terminated strings. Strings in Unix | |
1125 | kernels are not always null terminated. | |
1126 | ||
1127 | E\bEr\brr\bro\bor\brs\bs | |
1128 | ||
1129 | 0wpage | |
1130 | ||
1131 | 4\b4.\b.1\b19\b9.\b. r\bre\bea\bad\bdd\bdi\bir\br | |
1132 | ||
1133 | ||
1134 | S\bSu\bum\bmm\bma\bar\bry\by Read directory entries. | |
1135 | ||
1136 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
1137 | ||
1138 | i\bin\bn | |
1139 | ||
1140 | struct cfs_readdir_in { | |
1141 | ViceFid VFid; | |
1142 | int count; | |
1143 | int offset; | |
1144 | } cfs_readdir; | |
1145 | ||
1146 | ||
1147 | ||
1148 | ||
1149 | o\bou\but\bt | |
1150 | ||
1151 | struct cfs_readdir_out { | |
1152 | int size; | |
1153 | caddr_t data; /* Place holder for data. */ | |
1154 | } cfs_readdir; | |
1155 | ||
1156 | ||
1157 | ||
1158 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn Read directory entries from VFid starting at offset and | |
1159 | read at most count bytes. Returns the data in data and returns | |
1160 | the size in size. | |
1161 | ||
1162 | E\bEr\brr\bro\bor\brs\bs | |
1163 | ||
1164 | N\bNO\bOT\bTE\bE This call is not used. Readdir operations exploit container | |
1165 | files. We will re-evaluate this during the directory revamp which is | |
1166 | about to take place. | |
1167 | ||
1168 | 0wpage | |
1169 | ||
1170 | 4\b4.\b.2\b20\b0.\b. v\bvg\bge\bet\bt | |
1171 | ||
1172 | ||
1173 | S\bSu\bum\bmm\bma\bar\bry\by instructs Venus to do an FSDB->Get. | |
1174 | ||
1175 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
1176 | ||
1177 | i\bin\bn | |
1178 | ||
1179 | struct cfs_vget_in { | |
1180 | ViceFid VFid; | |
1181 | } cfs_vget; | |
1182 | ||
1183 | ||
1184 | ||
1185 | o\bou\but\bt | |
1186 | ||
1187 | struct cfs_vget_out { | |
1188 | ViceFid VFid; | |
1189 | int vtype; | |
1190 | } cfs_vget; | |
1191 | ||
1192 | ||
1193 | ||
1194 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn This upcall asks Venus to do a get operation on an fsobj | |
1195 | labelled by VFid. | |
1196 | ||
1197 | E\bEr\brr\bro\bor\brs\bs | |
1198 | ||
1199 | N\bNO\bOT\bTE\bE This operation is not used. However, it is extremely useful | |
1200 | since it can be used to deal with read/write memory mapped files. | |
1201 | These can be "pinned" in the Venus cache using vget and released with | |
1202 | inactive. | |
1203 | ||
1204 | 0wpage | |
1205 | ||
1206 | 4\b4.\b.2\b21\b1.\b. f\bfs\bsy\byn\bnc\bc | |
1207 | ||
1208 | ||
1209 | S\bSu\bum\bmm\bma\bar\bry\by Tell Venus to update the RVM attributes of a file. | |
1210 | ||
1211 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
1212 | ||
1213 | i\bin\bn | |
1214 | ||
1215 | struct cfs_fsync_in { | |
1216 | ViceFid VFid; | |
1217 | } cfs_fsync; | |
1218 | ||
1219 | ||
1220 | ||
1221 | o\bou\but\bt | |
1222 | none | |
1223 | ||
1224 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn Ask Venus to update RVM attributes of object VFid. This | |
1225 | should be called as part of kernel level fsync type calls. The | |
1226 | result indicates if the syncing was successful. | |
1227 | ||
1228 | E\bEr\brr\bro\bor\brs\bs | |
1229 | ||
1230 | N\bNO\bOT\bTE\bE Linux does not implement this call. It should. | |
1231 | ||
1232 | 0wpage | |
1233 | ||
1234 | 4\b4.\b.2\b22\b2.\b. i\bin\bna\bac\bct\bti\biv\bve\be | |
1235 | ||
1236 | ||
1237 | S\bSu\bum\bmm\bma\bar\bry\by Tell Venus a vnode is no longer in use. | |
1238 | ||
1239 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
1240 | ||
1241 | i\bin\bn | |
1242 | ||
1243 | struct cfs_inactive_in { | |
1244 | ViceFid VFid; | |
1245 | } cfs_inactive; | |
1246 | ||
1247 | ||
1248 | ||
1249 | o\bou\but\bt | |
1250 | none | |
1251 | ||
1252 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn This operation returns EOPNOTSUPP. | |
1253 | ||
1254 | E\bEr\brr\bro\bor\brs\bs | |
1255 | ||
1256 | N\bNO\bOT\bTE\bE This should perhaps be removed. | |
1257 | ||
1258 | 0wpage | |
1259 | ||
1260 | 4\b4.\b.2\b23\b3.\b. r\brd\bdw\bwr\br | |
1261 | ||
1262 | ||
1263 | S\bSu\bum\bmm\bma\bar\bry\by Read or write from a file | |
1264 | ||
1265 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
1266 | ||
1267 | i\bin\bn | |
1268 | ||
1269 | struct cfs_rdwr_in { | |
1270 | ViceFid VFid; | |
1271 | int rwflag; | |
1272 | int count; | |
1273 | int offset; | |
1274 | int ioflag; | |
1275 | caddr_t data; /* Place holder for data. */ | |
1276 | } cfs_rdwr; | |
1277 | ||
1278 | ||
1279 | ||
1280 | ||
1281 | o\bou\but\bt | |
1282 | ||
1283 | struct cfs_rdwr_out { | |
1284 | int rwflag; | |
1285 | int count; | |
1286 | caddr_t data; /* Place holder for data. */ | |
1287 | } cfs_rdwr; | |
1288 | ||
1289 | ||
1290 | ||
1291 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn This upcall asks Venus to read or write from a file. | |
1292 | ||
1293 | E\bEr\brr\bro\bor\brs\bs | |
1294 | ||
1295 | N\bNO\bOT\bTE\bE It should be removed since it is against the Coda philosophy that | |
1296 | read/write operations never reach Venus. I have been told the | |
1297 | operation does not work. It is not currently used. | |
1298 | ||
1299 | ||
1300 | 0wpage | |
1301 | ||
1302 | 4\b4.\b.2\b24\b4.\b. o\bod\bdy\bym\bmo\bou\bun\bnt\bt | |
1303 | ||
1304 | ||
1305 | S\bSu\bum\bmm\bma\bar\bry\by Allows mounting multiple Coda "filesystems" on one Unix mount | |
1306 | point. | |
1307 | ||
1308 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
1309 | ||
1310 | i\bin\bn | |
1311 | ||
1312 | struct ody_mount_in { | |
1313 | char *name; /* Place holder for data. */ | |
1314 | } ody_mount; | |
1315 | ||
1316 | ||
1317 | ||
1318 | o\bou\but\bt | |
1319 | ||
1320 | struct ody_mount_out { | |
1321 | ViceFid VFid; | |
1322 | } ody_mount; | |
1323 | ||
1324 | ||
1325 | ||
1326 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn Asks Venus to return the rootfid of a Coda system named | |
1327 | name. The fid is returned in VFid. | |
1328 | ||
1329 | E\bEr\brr\bro\bor\brs\bs | |
1330 | ||
1331 | N\bNO\bOT\bTE\bE This call was used by David for dynamic sets. It should be | |
1332 | removed since it causes a jungle of pointers in the VFS mounting area. | |
1333 | It is not used by Coda proper. Call is not implemented by Venus. | |
1334 | ||
1335 | 0wpage | |
1336 | ||
1337 | 4\b4.\b.2\b25\b5.\b. o\bod\bdy\by_\b_l\blo\boo\bok\bku\bup\bp | |
1338 | ||
1339 | ||
1340 | S\bSu\bum\bmm\bma\bar\bry\by Looks up something. | |
1341 | ||
1342 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
1343 | ||
1344 | i\bin\bn irrelevant | |
1345 | ||
1346 | ||
1347 | o\bou\but\bt | |
1348 | irrelevant | |
1349 | ||
1350 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn | |
1351 | ||
1352 | E\bEr\brr\bro\bor\brs\bs | |
1353 | ||
1354 | N\bNO\bOT\bTE\bE Gut it. Call is not implemented by Venus. | |
1355 | ||
1356 | 0wpage | |
1357 | ||
1358 | 4\b4.\b.2\b26\b6.\b. o\bod\bdy\by_\b_e\bex\bxp\bpa\ban\bnd\bd | |
1359 | ||
1360 | ||
1361 | S\bSu\bum\bmm\bma\bar\bry\by expands something in a dynamic set. | |
1362 | ||
1363 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
1364 | ||
1365 | i\bin\bn irrelevant | |
1366 | ||
1367 | o\bou\but\bt | |
1368 | irrelevant | |
1369 | ||
1370 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn | |
1371 | ||
1372 | E\bEr\brr\bro\bor\brs\bs | |
1373 | ||
1374 | N\bNO\bOT\bTE\bE Gut it. Call is not implemented by Venus. | |
1375 | ||
1376 | 0wpage | |
1377 | ||
1378 | 4\b4.\b.2\b27\b7.\b. p\bpr\bre\bef\bfe\bet\btc\bch\bh | |
1379 | ||
1380 | ||
1381 | S\bSu\bum\bmm\bma\bar\bry\by Prefetch a dynamic set. | |
1382 | ||
1383 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
1384 | ||
1385 | i\bin\bn Not documented. | |
1386 | ||
1387 | o\bou\but\bt | |
1388 | Not documented. | |
1389 | ||
1390 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn Venus worker.cc has support for this call, although it is | |
1391 | noted that it doesn't work. Not surprising, since the kernel does not | |
1392 | have support for it. (ODY_PREFETCH is not a defined operation). | |
1393 | ||
1394 | E\bEr\brr\bro\bor\brs\bs | |
1395 | ||
1396 | N\bNO\bOT\bTE\bE Gut it. It isn't working and isn't used by Coda. | |
1397 | ||
1398 | ||
1399 | 0wpage | |
1400 | ||
1401 | 4\b4.\b.2\b28\b8.\b. s\bsi\big\bgn\bna\bal\bl | |
1402 | ||
1403 | ||
1404 | S\bSu\bum\bmm\bma\bar\bry\by Send Venus a signal about an upcall. | |
1405 | ||
1406 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
1407 | ||
1408 | i\bin\bn none | |
1409 | ||
1410 | o\bou\but\bt | |
1411 | not applicable. | |
1412 | ||
1413 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn This is an out-of-band upcall to Venus to inform Venus | |
1414 | that the calling process received a signal after Venus read the | |
1415 | message from the input queue. Venus is supposed to clean up the | |
1416 | operation. | |
1417 | ||
1418 | E\bEr\brr\bro\bor\brs\bs No reply is given. | |
1419 | ||
1420 | N\bNO\bOT\bTE\bE We need to better understand what Venus needs to clean up and if | |
1421 | it is doing this correctly. Also we need to handle multiple upcall | |
1422 | per system call situations correctly. It would be important to know | |
1423 | what state changes in Venus take place after an upcall for which the | |
1424 | kernel is responsible for notifying Venus to clean up (e.g. open | |
1425 | definitely is such a state change, but many others are maybe not). | |
1426 | ||
1427 | 0wpage | |
1428 | ||
1429 | 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 | |
1430 | ||
1431 | ||
1432 | The Coda FS Driver can cache results of lookup and access upcalls, to | |
1433 | limit the frequency of upcalls. Upcalls carry a price since a process | |
1434 | context switch needs to take place. The counterpart of caching the | |
1435 | information is that Venus will notify the FS Driver that cached | |
1436 | entries must be flushed or renamed. | |
1437 | ||
1438 | The kernel code generally has to maintain a structure which links the | |
1439 | internal file handles (called vnodes in BSD, inodes in Linux and | |
1440 | FileHandles in Windows) with the ViceFid's which Venus maintains. The | |
1441 | reason is that frequent translations back and forth are needed in | |
1442 | order to make upcalls and use the results of upcalls. Such linking | |
1443 | objects are called c\bcn\bno\bod\bde\bes\bs. | |
1444 | ||
1445 | The current minicache implementations have cache entries which record | |
1446 | the following: | |
1447 | ||
1448 | 1. the name of the file | |
1449 | ||
1450 | 2. the cnode of the directory containing the object | |
1451 | ||
1452 | 3. a list of CodaCred's for which the lookup is permitted. | |
1453 | ||
1454 | 4. the cnode of the object | |
1455 | ||
1456 | The lookup call in the Coda FS Driver may request the cnode of the | |
1457 | desired object from the cache, by passing its name, directory and the | |
1458 | CodaCred's of the caller. The cache will return the cnode or indicate | |
1459 | that it cannot be found. The Coda FS Driver must be careful to | |
1460 | invalidate cache entries when it modifies or removes objects. | |
1461 | ||
1462 | When Venus obtains information that indicates that cache entries are | |
1463 | no longer valid, it will make a downcall to the kernel. Downcalls are | |
1464 | intercepted by the Coda FS Driver and lead to cache invalidations of | |
1465 | the kind described below. The Coda FS Driver does not return an error | |
1466 | unless the downcall data could not be read into kernel memory. | |
1467 | ||
1468 | ||
1469 | 5\b5.\b.1\b1.\b. I\bIN\bNV\bVA\bAL\bLI\bID\bDA\bAT\bTE\bE | |
1470 | ||
1471 | ||
1472 | No information is available on this call. | |
1473 | ||
1474 | ||
1475 | 5\b5.\b.2\b2.\b. F\bFL\bLU\bUS\bSH\bH | |
1476 | ||
1477 | ||
1478 | ||
1479 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs None | |
1480 | ||
1481 | S\bSu\bum\bmm\bma\bar\bry\by Flush the name cache entirely. | |
1482 | ||
1483 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn Venus issues this call upon startup and when it dies. This | |
1484 | is to prevent stale cache information being held. Some operating | |
1485 | systems allow the kernel name cache to be switched off dynamically. | |
1486 | When this is done, this downcall is made. | |
1487 | ||
1488 | ||
1489 | 5\b5.\b.3\b3.\b. P\bPU\bUR\bRG\bGE\bEU\bUS\bSE\bER\bR | |
1490 | ||
1491 | ||
1492 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
1493 | ||
1494 | struct cfs_purgeuser_out {/* CFS_PURGEUSER is a venus->kernel call */ | |
1495 | struct CodaCred cred; | |
1496 | } cfs_purgeuser; | |
1497 | ||
1498 | ||
1499 | ||
1500 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn Remove all entries in the cache carrying the Cred. This | |
1501 | call is issued when tokens for a user expire or are flushed. | |
1502 | ||
1503 | ||
1504 | 5\b5.\b.4\b4.\b. Z\bZA\bAP\bPF\bFI\bIL\bLE\bE | |
1505 | ||
1506 | ||
1507 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
1508 | ||
1509 | struct cfs_zapfile_out { /* CFS_ZAPFILE is a venus->kernel call */ | |
1510 | ViceFid CodaFid; | |
1511 | } cfs_zapfile; | |
1512 | ||
1513 | ||
1514 | ||
1515 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn Remove all entries which have the (dir vnode, name) pair. | |
1516 | This is issued as a result of an invalidation of cached attributes of | |
1517 | a vnode. | |
1518 | ||
1519 | N\bNO\bOT\bTE\bE Call is not named correctly in NetBSD and Mach. The minicache | |
1520 | zapfile routine takes different arguments. Linux does not implement | |
1521 | the invalidation of attributes correctly. | |
1522 | ||
1523 | ||
1524 | ||
1525 | 5\b5.\b.5\b5.\b. Z\bZA\bAP\bPD\bDI\bIR\bR | |
1526 | ||
1527 | ||
1528 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
1529 | ||
1530 | struct cfs_zapdir_out { /* CFS_ZAPDIR is a venus->kernel call */ | |
1531 | ViceFid CodaFid; | |
1532 | } cfs_zapdir; | |
1533 | ||
1534 | ||
1535 | ||
1536 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn Remove all entries in the cache lying in a directory | |
1537 | CodaFid, and all children of this directory. This call is issued when | |
1538 | Venus receives a callback on the directory. | |
1539 | ||
1540 | ||
1541 | 5\b5.\b.6\b6.\b. Z\bZA\bAP\bPV\bVN\bNO\bOD\bDE\bE | |
1542 | ||
1543 | ||
1544 | ||
1545 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
1546 | ||
1547 | struct cfs_zapvnode_out { /* CFS_ZAPVNODE is a venus->kernel call */ | |
1548 | struct CodaCred cred; | |
1549 | ViceFid VFid; | |
1550 | } cfs_zapvnode; | |
1551 | ||
1552 | ||
1553 | ||
1554 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn Remove all entries in the cache carrying the cred and VFid | |
1555 | as in the arguments. This downcall is probably never issued. | |
1556 | ||
1557 | ||
1558 | 5\b5.\b.7\b7.\b. P\bPU\bUR\bRG\bGE\bEF\bFI\bID\bD | |
1559 | ||
1560 | ||
1561 | S\bSu\bum\bmm\bma\bar\bry\by | |
1562 | ||
1563 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
1564 | ||
1565 | struct cfs_purgefid_out { /* CFS_PURGEFID is a venus->kernel call */ | |
1566 | ViceFid CodaFid; | |
1567 | } cfs_purgefid; | |
1568 | ||
1569 | ||
1570 | ||
1571 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn Flush the attribute for the file. If it is a dir (odd | |
1572 | vnode), purge its children from the namecache and remove the file from the | |
1573 | namecache. | |
1574 | ||
1575 | ||
1576 | ||
1577 | 5\b5.\b.8\b8.\b. R\bRE\bEP\bPL\bLA\bAC\bCE\bE | |
1578 | ||
1579 | ||
1580 | S\bSu\bum\bmm\bma\bar\bry\by Replace the Fid's for a collection of names. | |
1581 | ||
1582 | A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
1583 | ||
1584 | struct cfs_replace_out { /* cfs_replace is a venus->kernel call */ | |
1585 | ViceFid NewFid; | |
1586 | ViceFid OldFid; | |
1587 | } cfs_replace; | |
1588 | ||
1589 | ||
1590 | ||
1591 | D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn This routine replaces a ViceFid in the name cache with | |
1592 | another. It is added to allow Venus during reintegration to replace | |
1593 | locally allocated temp fids while disconnected with global fids even | |
1594 | when the reference counts on those fids are not zero. | |
1595 | ||
1596 | 0wpage | |
1597 | ||
1598 | 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 | |
1599 | ||
1600 | ||
1601 | This section gives brief hints as to desirable features for the Coda | |
1602 | FS Driver at startup and upon shutdown or Venus failures. Before | |
1603 | entering the discussion it is useful to repeat that the Coda FS Driver | |
1604 | maintains the following data: | |
1605 | ||
1606 | ||
1607 | 1. message queues | |
1608 | ||
1609 | 2. cnodes | |
1610 | ||
1611 | 3. name cache entries | |
1612 | ||
1613 | The name cache entries are entirely private to the driver, so they | |
1614 | can easily be manipulated. The message queues will generally have | |
1615 | clear points of initialization and destruction. The cnodes are | |
1616 | much more delicate. User processes hold reference counts in Coda | |
1617 | filesystems and it can be difficult to clean up the cnodes. | |
1618 | ||
1619 | It can expect requests through: | |
1620 | ||
1621 | 1. the message subsystem | |
1622 | ||
1623 | 2. the VFS layer | |
1624 | ||
1625 | 3. pioctl interface | |
1626 | ||
1627 | Currently the _\bp_\bi_\bo_\bc_\bt_\bl passes through the VFS for Coda so we can | |
1628 | treat these similarly. | |
1629 | ||
1630 | ||
1631 | 6\b6.\b.1\b1.\b. R\bRe\beq\bqu\bui\bir\bre\bem\bme\ben\bnt\bts\bs | |
1632 | ||
1633 | ||
1634 | The following requirements should be accommodated: | |
1635 | ||
1636 | 1. The message queues should have open and close routines. On Unix | |
1637 | the opening of the character devices are such routines. | |
1638 | ||
1639 | +\bo Before opening, no messages can be placed. | |
1640 | ||
1641 | +\bo Opening will remove any old messages still pending. | |
1642 | ||
1643 | +\bo Close will notify any sleeping processes that their upcall cannot | |
1644 | be completed. | |
1645 | ||
1646 | +\bo Close will free all memory allocated by the message queues. | |
1647 | ||
1648 | ||
1649 | 2. At open the namecache shall be initialized to empty state. | |
1650 | ||
1651 | 3. Before the message queues are open, all VFS operations will fail. | |
1652 | Fortunately this can be achieved by making sure than mounting the | |
1653 | Coda filesystem cannot succeed before opening. | |
1654 | ||
1655 | 4. After closing of the queues, no VFS operations can succeed. Here | |
1656 | one needs to be careful, since a few operations (lookup, | |
1657 | read/write, readdir) can proceed without upcalls. These must be | |
1658 | explicitly blocked. | |
1659 | ||
1660 | 5. Upon closing the namecache shall be flushed and disabled. | |
1661 | ||
1662 | 6. All memory held by cnodes can be freed without relying on upcalls. | |
1663 | ||
1664 | 7. Unmounting the file system can be done without relying on upcalls. | |
1665 | ||
1666 | 8. Mounting the Coda filesystem should fail gracefully if Venus cannot | |
1667 | get the rootfid or the attributes of the rootfid. The latter is | |
1668 | best implemented by Venus fetching these objects before attempting | |
1669 | to mount. | |
1670 | ||
1671 | N\bNO\bOT\bTE\bE NetBSD in particular but also Linux have not implemented the | |
1672 | above requirements fully. For smooth operation this needs to be | |
1673 | corrected. | |
1674 | ||
1675 | ||
1676 |