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