Document FSSYNC commands
[openafs.git] / src / vol / fssync.h
1 /*
2  * Copyright 2000, International Business Machines Corporation and others.
3  * All Rights Reserved.
4  * 
5  * This software has been released under the terms of the IBM Public
6  * License.  For details, see the LICENSE file in the top-level source
7  * directory or online at http://www.openafs.org/dl/license10.html
8  *
9  * Portions Copyright (c) 2006-2008 Sine Nomine Associates
10  */
11
12 /*
13         System:         VICE-TWO
14         Module:         fssync.h
15         Institution:    The Information Technology Center, Carnegie-Mellon University
16
17  */
18
19 #ifndef __fssync_h_
20 #define __fssync_h_
21
22
23 #define FSYNC_PROTO_VERSION     3
24
25
26 /**
27  * FSYNC command codes.
28  *
29  * If you add more command codes here, be sure to add some documentation
30  * in doc/arch/fssync.txt.
31  */
32 enum FSYNCOpCode {
33     FSYNC_VOL_ON              = SYNC_COM_CODE_DECL(0),  /**< bring Volume online */
34     FSYNC_VOL_OFF             = SYNC_COM_CODE_DECL(1),  /**< take Volume offline */
35     FSYNC_VOL_LISTVOLUMES     = SYNC_COM_CODE_DECL(2),  /**< Update local volume list */
36     FSYNC_VOL_NEEDVOLUME      = SYNC_COM_CODE_DECL(3),  /**< Put volume in whatever mode (offline, or whatever)
37                                                          *   best fits the attachment mode provided in reason */
38     FSYNC_VOL_MOVE            = SYNC_COM_CODE_DECL(4),  /**< Generate temporary relocation information
39                                                          *   for this volume to another site, to be used
40                                                          *   if this volume disappears */
41     FSYNC_VOL_BREAKCBKS       = SYNC_COM_CODE_DECL(5),  /**< Break all the callbacks on this volume */
42     FSYNC_VOL_DONE            = SYNC_COM_CODE_DECL(6),  /**< Done with this volume (used after a delete).
43                                                          *   Don't put online, but remove from list */
44     FSYNC_VOL_QUERY           = SYNC_COM_CODE_DECL(7),  /**< query the volume state */
45     FSYNC_VOL_QUERY_HDR       = SYNC_COM_CODE_DECL(8),  /**< query the volume disk data structure */
46     FSYNC_VOL_QUERY_VOP       = SYNC_COM_CODE_DECL(9),  /**< query the volume for pending vol op info */
47     FSYNC_VOL_STATS_GENERAL   = SYNC_COM_CODE_DECL(10), /**< query the general volume package statistics */
48     FSYNC_VOL_STATS_VICEP     = SYNC_COM_CODE_DECL(11), /**< query the per-partition volume package stats */
49     FSYNC_VOL_STATS_HASH      = SYNC_COM_CODE_DECL(12), /**< query the per hash-chain volume package stats */
50     FSYNC_VOL_STATS_HDR       = SYNC_COM_CODE_DECL(13), /**< query the volume header cache statistics */
51     FSYNC_VOL_STATS_VLRU      = SYNC_COM_CODE_DECL(14), /**< query the VLRU statistics */
52     FSYNC_VOL_ATTACH          = SYNC_COM_CODE_DECL(15), /**< Force volume online */
53     FSYNC_VOL_FORCE_ERROR     = SYNC_COM_CODE_DECL(16), /**< force volume into error state */
54     FSYNC_VOL_LEAVE_OFF       = SYNC_COM_CODE_DECL(17), /**< end vol op, but leave volume offline */
55     FSYNC_VOL_QUERY_VNODE     = SYNC_COM_CODE_DECL(18), /**< query vnode state */
56     FSYNC_OP_CODE_END
57 };
58
59 /**
60  * FSYNC reason codes. 
61  */
62 enum FSYNCReasonCode {
63     FSYNC_WHATEVER            = SYNC_REASON_CODE_DECL(0), /**< XXXX */
64     FSYNC_SALVAGE             = SYNC_REASON_CODE_DECL(1), /**< volume is being salvaged */
65     FSYNC_MOVE                = SYNC_REASON_CODE_DECL(2), /**< volume is being moved */
66     FSYNC_OPERATOR            = SYNC_REASON_CODE_DECL(3), /**< operator forced volume offline */
67     FSYNC_EXCLUSIVE           = SYNC_REASON_CODE_DECL(4), /**< somebody else has the volume offline */
68     FSYNC_UNKNOWN_VOLID       = SYNC_REASON_CODE_DECL(5), /**< volume id not known by fileserver */
69     FSYNC_HDR_NOT_ATTACHED    = SYNC_REASON_CODE_DECL(6), /**< volume header not currently attached */
70     FSYNC_NO_PENDING_VOL_OP   = SYNC_REASON_CODE_DECL(7), /**< no volume operation pending */
71     FSYNC_VOL_PKG_ERROR       = SYNC_REASON_CODE_DECL(8), /**< error in the volume package */
72     FSYNC_UNKNOWN_VNID        = SYNC_REASON_CODE_DECL(9), /**< vnode id not known by fileserver */
73     FSYNC_WRONG_PART          = SYNC_REASON_CODE_DECL(10),/**< volume attached on different partition */
74     FSYNC_BAD_STATE           = SYNC_REASON_CODE_DECL(11),/**< current volume state does not allow this operation */
75     FSYNC_REASON_CODE_END
76 };
77
78 /* FSYNC response codes */
79
80 /* FSYNC flag codes */
81
82 struct offlineInfo {
83     afs_uint32 volumeID;
84     char partName[16];
85 };
86
87 /**
88  * fssync protocol volume operation request message.
89  */
90 typedef struct FSSYNC_VolOp_hdr {
91     afs_uint32 volume;          /**< volume id associated with request */
92     char partName[16];          /**< partition name, e.g. /vicepa */
93 } FSSYNC_VolOp_hdr;
94
95 typedef struct FSSYNC_VolOp_command {
96     SYNC_command_hdr * hdr;
97     FSSYNC_VolOp_hdr * vop;
98     SYNC_command * com;
99     struct offlineInfo * v;
100     struct offlineInfo * volumes;
101 } FSSYNC_VolOp_command;
102
103
104 /**
105  * volume operation processing state.
106  */
107 enum FSSYNC_VolOpState {
108     FSSYNC_VolOpPending        = 0, /**< volume operation request received */
109     FSSYNC_VolOpDenied         = 1, /**< volume operation request denied */
110     FSSYNC_VolOpRunningOnline  = 2, /**< volume operation is running while volume is online */
111     FSSYNC_VolOpRunningOffline = 3, /**< volume operation is running while volume is offline */
112     FSSYNC_VolOpRunningUnknown = 4 /**< volume operation is running; VVolOpLeaveOnline_r resolution unknown */
113 };
114
115 /**
116  * volume operation information node.
117  *
118  * @note this structure is attached to a struct Volume to signify that
119  *       a volume operation is in-progress.
120  *
121  * @see Volume
122  * @see VRegisterVolOp_r
123  * @see VDeregisterVolOp_r
124  */
125 typedef struct FSSYNC_VolOp_info {
126     SYNC_command_hdr com;
127     FSSYNC_VolOp_hdr vop;
128     enum FSSYNC_VolOpState vol_op_state; 
129 } FSSYNC_VolOp_info;
130
131
132 /**
133  * fssync protocol volume package statistics request node.
134  */
135 typedef struct FSSYNC_StatsOp_hdr {
136     union {
137         afs_uint32 vlru_generation;     /**< vlru generation id */
138         afs_uint32 hash_bucket;         /**< volume hash bucket */
139         char partName[16];              /**< partition name */
140     } args;
141 } FSSYNC_StatsOp_hdr;
142
143 typedef struct FSSYNC_StatsOp_command {
144     SYNC_command_hdr * hdr;
145     FSSYNC_StatsOp_hdr * sop;
146     SYNC_command * com;
147 } FSSYNC_StatsOp_command;
148
149 /**
150  * fssync protocol vnode query request message.
151  */
152 typedef struct FSSYNC_VnQry_hdr {
153     afs_uint32 volume;          /**< volume id */
154     afs_uint32 vnode;           /**< vnode id */
155     afs_uint32 unique;          /**< uniqifier */
156     afs_uint32 spare;           /**< reserved for future use */
157     char partName[16];          /**< partition name */
158 } FSSYNC_VnQry_hdr;
159
160
161 #define FSSYNC_IN_PORT 2040
162 #define FSSYNC_UN_PATH "fssync.sock"
163 #define FSSYNC_ENDPOINT_DECL    SYNC_ENDPOINT_DECL(FSSYNC_IN_PORT, FSSYNC_UN_PATH)
164
165 /*
166  * common interfaces
167  */
168 extern void FSYNC_Init(void);
169
170 /* 
171  * fsync client interfaces 
172  */
173 extern void FSYNC_clientFinis(void);
174 extern int FSYNC_clientInit(void);
175 extern int FSYNC_clientChildProcReconnect(void);
176
177 /* generic low-level interface */
178 extern afs_int32 FSYNC_askfs(SYNC_command * com, SYNC_response * res);
179
180 /* generic higher-level interface */
181 extern afs_int32 FSYNC_GenericOp(void * ext_hdr, size_t ext_len,
182                                  int command, int reason,
183                                  SYNC_response * res);
184
185 /* volume operations interface */
186 extern afs_int32 FSYNC_VolOp(VolumeId volume, char *partName, int com, int reason, 
187                              SYNC_response * res);
188
189 /* statistics query interface */
190 extern afs_int32 FSYNC_StatsOp(FSSYNC_StatsOp_hdr * scom, int command, int reason,
191                                SYNC_response * res_in);
192
193 extern void FSYNC_fsInit(void);
194
195 #endif /* __fssync_h_ */