PERFORCE change 101484 for review
Adam Martin
adamartin at FreeBSD.org
Thu Jul 13 18:13:21 UTC 2006
http://perforce.freebsd.org/chv.cgi?CH=101484
Change 101484 by adamartin at 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 ***/
More information about the p4-projects
mailing list