Date: Fri, 7 Jul 2006 19:31:48 GMT From: Adam Martin <adamartin@FreeBSD.org> To: Perforce Change Reviews <perforce@FreeBSD.org> Subject: PERFORCE change 100930 for review Message-ID: <200607071931.k67JVmqH064008@repoman.freebsd.org>
next in thread | raw e-mail | index | archive | help
http://perforce.freebsd.org/chv.cgi?CH=100930 Change 100930 by adamartin@adamartin_tethys on 2006/07/07 19:31:09 Updates to protocol header, and a document describing the way it works. More updates are queued to go, but I want to record this intermediate work, which Erez has reviewed. Affected files ... .. //depot/projects/soc2006/adamartin_autofs/AutoFS-Proposal/AutoFS.protocol#1 add .. //depot/projects/soc2006/adamartin_autofs/AutoFS-Proposal/protocol_datatypes.h#2 edit Differences ... ==== //depot/projects/soc2006/adamartin_autofs/AutoFS-Proposal/protocol_datatypes.h#2 (text+ko) ==== @@ -1,14 +1,15 @@ #ifndef AUTOFS_PROTOCOL_HEADER #define AUTOFS_PROTOCOL_HEADER -/***** The protocol between AutoFS and AMD consists of these data types, +/***** The protocol between AutoFS and Automounter consists of these data types, strung together, as explained below. *****/ -#define MAX_PATH_LENGTH ( 1024 ) struct message_header { + uint64_t flags; /** 64 bits of flags, for some future usage, yet to + be determined. **/ uint64_t transaction_id; /** negative 1 and 0 are reserved tid's **/ uint32_t message_type; void message_data[]; /** You re-cast this handle to the @@ -16,48 +17,72 @@ }; -#define AUTOFS_ACK ( 0x20 ) +#define COMMAND_ACK ( 0x20 ) + +#define COMMAND_ACKNOWLEDGE ( COMMAND_ACK ) + +/** The ACK command can be sent by either party, AutoFS or Automounter, to +terminate a transaction. Question: Should all transactions end with an ACK? +Further Question: Should all commands end on the AutoFS side? **/ + + -#define AUTOFS_MOUNT_REQUEST ( 0x01 ) +#define COMMAND_MOUNT_REQUEST ( 0x01 ) struct mount_request +/** This is normally sent by AutoFS to Automounter, except under one specific +circumstance, where Automounter can send an unmount request to AutoFS. This is +explained in the examples file. **/ { uint32_t action; /** Mount or unmount **/ - char mountpoint [ MAX_PATH_LENGTH ]; +# define ACTION_MOUNT ( 0x01 ) +# define ACTION_UNMOUNT ( 0x02 ) + char mountpoint[]; }; -#define AUTOFS_MOUNT ( 0x01 ) -#define AUTOFS_UNMOUNT ( 0x02 ) -#define AUTOFS_MOUNT_DONE ( 0x02 ) +#define COMMAND_MOUNT_DONE ( 0x02 ) struct mount_done +/** Automounter returns this after any mount command **/ { uint32_t status; /** Failed, succeeded, etc. **/ }; -#define AUTOFS_AMD_HELLO ( 0x03 ) +#define COMMAND_HELLO ( 0x03 ) -struct autofs_amd_hello +struct hello +/** Automounter sends this command to initiate a session with the AutoFS **/ { uint32_t proto_ver; }; -#define AUTOFS_GREETING ( 0x04 ) struct managed_mount +/** This structure is supplemental to mount management commands. Both AutoFS +and Automounter commands use this format to encode the mountpoints that will +be managed. **/ { uint32_t status; + /** Automounter uses the status field to encode the action to perform, + (add or remove from the list) at current. AutoFS will report the + status of managed mounts in this same field to Automounter -- mounted, + unmounted, etc. **/ uint32_t timeout; /** In seconds? **/ uint32_t type; /** Network, local, etc. We can define several types later. **/ - char mountpoint [ MAX_PATH_LENGTH ]; + char mountpoint[]; +} -struct autofs_greeting +#define COMMAND_AUTOFS_GREETING ( 0x04 ) +struct greeting +/** AutoFS sends this command to Automounter, after getting the "Hello" +command. Automounter should parse the mount management list, to check any +state it must record, and to take any appropriate actions. **/ { uint32_t status; uint32_t proto_ver; @@ -67,19 +92,49 @@ -#define AUTOFS_AMD_GREETING ( 0x05 ) +#define COMMAND_GREETING_RESPONSE ( 0x05 ) -struct amd_greeting_response +struct greeting_response +/** Automounter will send this command to finish an initialization transaction. +AutoFS will modify its internal mount management table to reflect Automounter's wishes, and handle the new mountpoints **/ { uint32_t session_id; - uint32_t list_action; /** Append to list, replace list, perhaps we - can add others later? **/ uint32_t n_mounts; struct managed_mount mounts[]; }; + +#define COMMAND_MODIFY_MOUNTS ( 0x06 ) + +struct modify_mounts +/** Automounter can send this command at any time, to re-initialize, or modify +mounts. Automounter should never have more than ONE mount-modification request +in flight at any given time, as TID's are only generated by AutoFS.**/ + +/** Question for FreeBSD folk, and Prof. Zadok: What if we let Automounter +generate the TID field here, and AutoFS merely copies that field back, when +replying? We cannot guarantee the isolation of these transactions, but +Automounter can re-use TID's from transactions it wants to interlace with +modify_mount actions? **/ +{ + uint32_t n_mounts; + struct managed_mount mounts[]; +} + +#define COMMAND_MODIFY_MOUNTS_ACKNOWLEDGE ( 0x07 ) + +struct modify_mounts_acknowledge +/** AutoFS will issue this command in response to either of a modify_mounts +command, or a greetings_response command. The status field of mounts, in this +case, is the success or failure of modifying the mount table as requested by +the matching slot in the modify_mounts or greetings_response command. **/ +{ + uint32_t n_mounts; + struct managed_mounts mounts[]; +} + /**** -How it all works: +How it all works: (See AutoFS.protocol for a detailed explanation) Each side drops raw data into the data-pipe (a pseudo-device) and picks it up from this data-pipe. From the perspective of the protocol handler, on either @@ -87,13 +142,14 @@ received, the handler should first apply the "protocol_header" struct to the bytes. From that point, a switch statement on the "type" field in the header determines the next structure to use, attached to the next field of bytes. On -unknown types, AutoFS should send a response back to AMD, and request AMD to -restart? Similarly so with AMD. This part I suppose could be made better? +unknown types, AutoFS should send a response back to Automounter, and request +Automounter to restart? Similarly so with Automounter. This part I suppose +could be made better? Generally, the nature of interaction goes something like this: -AMD AutoFS -Hello +Automounter AutoFS +Hello, I would like to talk protocol version XYZZY @@ -108,46 +164,50 @@ Any mounted filesystems will preclude the capability to replace the existing list in -AutoFS. AMD must be instructed -to unmount those filesystems. +AutoFS. Automounter must be +instructed to unmount those +filesystems. + - Acknowledge + modify_mounts_acknowledge ------------------ sometime later a mount is requested -------------------- Please mount filesystem xyzzy -AMD will perform the -mounting, and then when -finished, will notfiy -AutoFS of the status -of the attempt (fail -or succeed.) +Automounter will perform +the mounting, and then +when finished, will +notfiy AutoFS of the +status of the attempt +(fail or succeed.) Acknowledge ----------------- a similar process is incurred for unmount -------------- -Additionally for unmount, AMD my request that AutoFS be notified of -an unmount attempt. Such a transaction will look like this: +Additionally for unmount, Automounter my request that AutoFS be notified of an +unmount attempt. Such a transaction will look like this: -AMD will send an unmount -request for xyzzy, without -a TID stamp. (0, perhaps?) +Automounter will send an +unmount request for xyzzy, +without a TID stamp. (use +a 0 perhaps?) AutoFS will send back an identical request with a generated timestamp. -AMD will perform the unmount -and then notify as normal. +Automounter will perform the +unmount and then notify as +normal. Acknowledge. ---------------------------------------------------------------------- -If AutoFS receives a greeting request from an already established AMD session, -AutoFS will interpret this as an attempt to re-synchronize the state between -the two entities. All the primary rules apply. +If AutoFS receives a greeting request from an already established Automounter +session, AutoFS will interpret this as an attempt to re-synchronize the state +between the two entities. All the primary rules apply. The AutoFS devices will only allow ONE process to be connected to them at any given time. (This obviously precludes child-processes, which AutoFS will
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200607071931.k67JVmqH064008>