From owner-p4-projects@FreeBSD.ORG Thu Jul 13 18:13:21 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 DE56616A4E1; Thu, 13 Jul 2006 18:13:20 +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 A052516A4DF for ; Thu, 13 Jul 2006 18:13:20 +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 8B24B43D67 for ; Thu, 13 Jul 2006 18:12:56 +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 k6DICuYC058698 for ; Thu, 13 Jul 2006 18:12:56 GMT (envelope-from adamartin@FreeBSD.org) Received: (from perforce@localhost) by repoman.freebsd.org (8.13.6/8.13.4/Submit) id k6DICu6P058695 for perforce@freebsd.org; Thu, 13 Jul 2006 18:12:56 GMT (envelope-from adamartin@FreeBSD.org) Date: Thu, 13 Jul 2006 18:12:56 GMT Message-Id: <200607131812.k6DICu6P058695@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 101484 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: Thu, 13 Jul 2006 18:13:21 -0000 http://perforce.freebsd.org/chv.cgi?CH=101484 Change 101484 by adamartin@adamartin_tethys on 2006/07/13 18:12:14 Updates to the protocol description. Also moved protocol_datatypes.h to style( 9 ) and improved documentation of the file. Later today I will submit some of the initial development implementation. Affected files ... .. //depot/projects/soc2006/adamartin_autofs/AutoFS-Proposal/AutoFS.protocol#2 edit .. //depot/projects/soc2006/adamartin_autofs/AutoFS-Proposal/protocol_datatypes.h#3 edit Differences ... ==== //depot/projects/soc2006/adamartin_autofs/AutoFS-Proposal/AutoFS.protocol#2 (text+ko) ==== ==== //depot/projects/soc2006/adamartin_autofs/AutoFS-Proposal/protocol_datatypes.h#3 (text+ko) ==== @@ -1,71 +1,34 @@ #ifndef AUTOFS_PROTOCOL_HEADER #define AUTOFS_PROTOCOL_HEADER -/***** The protocol between AutoFS and Automounter consists of these data types, -strung together, as explained below. *****/ +/* + * The protocol between AutoFS and Automounter consists of these data types, + * strung together, as explained below. + */ - -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 - structure type as needed. **/ +/* + * This is the protocol message header. All messages between AutoFS + * and Automounter start with this header. Transaction id's, and other + * pertinent information is encoded into this header. + */ +struct message_header { + uint64_t flags; /* flags, for some usage, yet to be determined. */ + uint64_t transaction_id; /* Used to identify which transaction + the message pertains to. */ + uint32_t message_type; /* Used to identify which command is issued in + this packet. COMMAND_* constants are used to fill these */ + void message_data[]; /* The rest of the message data, as an + indeterminate length. */ }; -#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 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 **/ -# define ACTION_MOUNT ( 0x01 ) -# define ACTION_UNMOUNT ( 0x02 ) - char mountpoint[]; -}; - - - - -#define COMMAND_MOUNT_DONE ( 0x02 ) - -struct mount_done -/** Automounter returns this after any mount command **/ -{ - uint32_t status; /** Failed, succeeded, etc. **/ -}; - -#define COMMAND_HELLO ( 0x03 ) - -struct hello -/** Automounter sends this command to initiate a session with the AutoFS **/ -{ - uint32_t proto_ver; -}; - - - -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. **/ -{ +/* + * This structure is supplemental to mount management commands. Both AutoFS + * and Automounter commands use this format to encode the mountpoints that + * will be managed. + */ +struct managed_mount { 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 @@ -74,145 +37,157 @@ uint32_t timeout; /** In seconds? **/ uint32_t type; /** Network, local, etc. We can define several types later. **/ + uint32_t mountpoint_len; char mountpoint[]; -} +}; -#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; - uint32_t n_mounts; - struct managed_mount mounts[]; -}; + + +/* + * The commands for the protocol and their attendant argument structures + * are all detailed below. + */ + + +/* + * ACK is the acknowledge command. It can be sent by either the Kernel + * or the Automounter, in specific circumstances. + * + * Question: Should all transactions end with an ACK? + * Further Question: Should all commands end on the AutoFS side? + */ +#define COMMAND_ACK ( 0x20 ) -#define COMMAND_GREETING_RESPONSE ( 0x05 ) +/* + * There is no further structure for an ACK command + */ -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 n_mounts; - struct managed_mount mounts[]; -}; -#define COMMAND_MODIFY_MOUNTS ( 0x06 ) +/* + * 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. + */ +#define COMMAND_MOUNT_REQUEST ( 0x01 ) -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.**/ +struct mount_request { + uint32_t action; /* The ACTION_* constants defined below are + used to specify the kind of action being requested */ + #define ACTION_MOUNT ( 0x01 ) /* Mount a path */ + #define ACTION_UNMOUNT ( 0x02 ) /* Unmount a path */ + uint32_t mountpoint_len; /* Length of mountpoint field that follows */ + char mountpoint[]; /* Location to perform this mount-related action */ +}; -/** 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[]; -} +/* + * The Automounter will return this after any mount command. The mount-related + * action may have succeeded or failed. The Automounter should report this + * status, and perhaps detail reasons for failure (EBUSY, etc.?) + */ +#define COMMAND_MOUNT_DONE ( 0x02 ) -/**** -How it all works: (See AutoFS.protocol for a detailed explanation) +struct mount_done { + uint32_t status; /* Status of the mount-related attempt */ + +}; -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 -end, this data is a raw stream of bytes. Starting from the first byte, ever -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 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: -Automounter AutoFS -Hello, -I would like to talk -protocol version XYZZY +/* + * Automounter sends this command to initiate a session with the AutoFS. + * Further interaction is used to determine the specific kind of protocol + * to speak. In this message, the Automounter suggests to AutoFS a protocol + * version that will be spoken. + */ +#define COMMAND_HELLO ( 0x03 ) - Greetings, - The version I can talk is PLOVER - here is the list of filesystems I currently - manage, and their individual states. +struct hello { + uint32_t proto_ver; /* The requested version to speak */ +}; -Greetings back, please -modify your management list -to include these filesystems. -Any mounted filesystems will -preclude the capability to -replace the existing list in -AutoFS. Automounter must be -instructed to unmount those -filesystems. - modify_mounts_acknowledge +/* + * AutoFS sends this command to Automounter, after getting the "Hello" + * command. The Automounter should parse the mount management list, to + * check any state it must record, and to take any appropriate actions. + * The reported protocol version is the highest version of the protocol + * which the kernel can support. It is expected that the kernel suggested + * version will be adopted by the userspace. (If a user client supports + * X+3 it implicitly supports X, X+1 and X+2 as well. + */ +#define COMMAND_AUTOFS_GREETING ( 0x04 ) ------------------- sometime later a mount is requested -------------------- +struct greeting { + uint32_t status; /* The status of the greeting. This may have future + use. */ + uint32_t proto_ver; /* Kernel supported protocol. */ + uint32_t n_mounts; /* Number of mounts to report */ + struct managed_mount mounts[]; /* current notion of mount state */ +}; - Please mount filesystem xyzzy -Automounter will perform -the mounting, and then -when finished, will -notfiy AutoFS of the -status of the attempt -(fail or succeed.) - Acknowledge +/* + * 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. + */ +#define COMMAND_GREETING_RESPONSE ( 0x05 ) +struct greeting_response { + uint32_t session_id; + uint32_t n_mounts; + struct managed_mount mounts[]; +}; ------------------ a similar process is incurred for unmount -------------- -Additionally for unmount, Automounter my request that AutoFS be notified of an -unmount attempt. Such a transaction will look like this: -Automounter will send an -unmount request for xyzzy, -without a TID stamp. (use -a 0 perhaps?) +/* + * 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? + * + * Erez has suggested letting User and Kernel TID's share the TID space, but + * have all high-bit set TID's be user, and clear be kernel. + */ - AutoFS will send back an identical request - with a generated timestamp. +#define COMMAND_MODIFY_MOUNTS ( 0x06 ) -Automounter will perform the -unmount and then notify as -normal. +struct modify_mounts { + uint32_t n_mounts; /* Number of managed_mount entries in payload */ + struct managed_mount mounts[]; /* the mounts to be changed */ +}; - Acknowledge. ----------------------------------------------------------------------- -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 -believe are the same as the parent perhaps, to facilitate communications?) +/* + * 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. + */ +#define COMMAND_MODIFY_MOUNTS_ACKNOWLEDGE ( 0x07 ) -*****/ +struct modify_mounts_acknowledge { + uint32_t n_mounts; /* Number of entries that are in response */ + struct managed_mounts mounts[]; /* The mount entries, and correspondant + status of action */ +}; #endif /*** AUTOFS_PROTOCOL_HEADER ***/