From owner-p4-projects@FreeBSD.ORG Fri Jul 7 19:32:18 2006 Return-Path: X-Original-To: p4-projects@freebsd.org Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id B4A6616A4EA; Fri, 7 Jul 2006 19:32:18 +0000 (UTC) X-Original-To: perforce@FreeBSD.org Delivered-To: perforce@FreeBSD.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 6906616A4E5 for ; Fri, 7 Jul 2006 19:32:18 +0000 (UTC) (envelope-from adamartin@FreeBSD.org) Received: from repoman.freebsd.org (repoman.freebsd.org [216.136.204.115]) by mx1.FreeBSD.org (Postfix) with ESMTP id 2A92D43D58 for ; Fri, 7 Jul 2006 19:31:49 +0000 (GMT) (envelope-from adamartin@FreeBSD.org) Received: from repoman.freebsd.org (localhost [127.0.0.1]) by repoman.freebsd.org (8.13.6/8.13.6) with ESMTP id k67JVn6F064011 for ; Fri, 7 Jul 2006 19:31:49 GMT (envelope-from adamartin@FreeBSD.org) Received: (from perforce@localhost) by repoman.freebsd.org (8.13.6/8.13.4/Submit) id k67JVmqH064008 for perforce@freebsd.org; Fri, 7 Jul 2006 19:31:48 GMT (envelope-from adamartin@FreeBSD.org) Date: Fri, 7 Jul 2006 19:31:48 GMT Message-Id: <200607071931.k67JVmqH064008@repoman.freebsd.org> X-Authentication-Warning: repoman.freebsd.org: perforce set sender to adamartin@FreeBSD.org using -f From: Adam Martin To: Perforce Change Reviews Cc: Subject: PERFORCE change 100930 for review X-BeenThere: p4-projects@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: p4 projects tree changes List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 07 Jul 2006 19:32:19 -0000 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