From: Andrew Deason Date: Thu, 4 Feb 2010 19:00:47 +0000 (-0600) Subject: Document FSSYNC commands X-Git-Tag: openafs-devel-1_5_73~188 X-Git-Url: https://git.openafs.org/?p=openafs.git;a=commitdiff_plain;h=769be238b07897e94e77fa9b7743a53d8f887535 Document FSSYNC commands Provide some explanation for the various FSSYNC commands, and what they are there for. Change-Id: I572300b66cc8b6a1b0f2aa185edd198c237f7225 Reviewed-on: http://gerrit.openafs.org/1236 Reviewed-by: Derrick Brashear Tested-by: Derrick Brashear --- diff --git a/doc/arch/fssync.txt b/doc/arch/fssync.txt new file mode 100644 index 0000000..0de1c81 --- /dev/null +++ b/doc/arch/fssync.txt @@ -0,0 +1,198 @@ +This file provides a brief description of the commands of the FSSYNC +protocol, and how/why each are typically used. + + -- vol op FSSYNC commands + +FSSYNC commands involving volume operations take a FSSYNC_VolOp_command +struct as their command and arguments. They all deal with a specific +volume, so "the specified volume" below refers to the volume in the +FSSYNC_VolOp_hdr in the FSSYNC_VolOp_command. + + -- FSYNC_VOL_ON + +Tells the fileserver to bring the specified volume online. For DAFS, +this brings the volume into the preattached state. For non-DAFS, the +volume is attached. + +This is generally used to tell the fileserver about a newly-created +volume, or to return ('check in') a volume to the fileserver that was +previously checked-out (e.g. via FSYNC_VOL_NEEDVOLUME). + + -- FSYNC_VOL_OFF + +Tells the fileserver to take a volume offline, so nothing else will +access the volume until it is brought online via FSSYNC again. A volume +that is offlined with this command and the FSYNC_SALVAGE reason code +will not be allowed access from the fileserver by anything. The volume +will be 'checked out' until it is 'checked in' by another FSYNC command. + +Currently only the salvaging code uses this command; the only difference +between it an FSYNC_VOL_NEEDVOLUME is the logic that determines whether +an offlined volume can be accessed by other programs or not. + + -- FSYNC_VOL_LISTVOLUMES + +This is currently a no-op; all it does is return success, assuming the +FSSYNC command is well-formed. + +In Transarc/IBM AFS 3.1, this was used to create a file listing all +volumes on the server, and was used with a tool to create a list of +volumes to backup. After AFS 3.1, however, it never did anything. + + -- FSYNC_VOL_NEEDVOLUME + +Tells the fileserver that the calling program needs the volume for a +certain operation. The fileserver will offline the volume or keep it +online, depending on the reason code given. The volume will be marked as +'checked out' until 'checked in' again with another FSYNC command. + +Reason codes for this command are different than for normal FSSYNC +commands; reason codes for _NEEDVOLUME are volume checkout codes like +V_CLONE, V_DUMP, and the like. The fileserver will keep the volume +online if the given reason code is V_READONLY, or if the volume is an RO +volume and the given reason code is V_CLONE or V_DUMP. If the volume is +taken offline, the volume's specialStatus will also be marked with VBUSY +in the case of the V_CLONE or V_DUMP reason codes. + + -- FSYNC_VOL_MOVE + +Tells the fileserver that the specified volume was moved to a new site. +The new site is given in the reason code of the request. On receiving +this, the fileserver merely sets the specialStatus on the volume, and +breaks all of the callbacks on the volume. + + -- FSYNC_VOL_BREAKCBKS + +Tells the fileserver to break all callbacks with the specified volume. +This is used when volumes are deleted or overwritten (restores, +reclones, etc). + + -- FSYNC_VOL_DONE + +Tells the fileserver that a volume has been deleted. This is actually +similar to FSYNC_VOL_ON, except that the volume isn't onlined. The +volume is 'checked in', though, and is removed from the list of volumes. + + -- FSYNC_VOL_QUERY + +Asks the fileserver to provide the known volume state information for +the specified volume. If the volume is known, the response payload is a +filled-in 'struct Volume'. + +This is used as a debugging tool to query volume state in the +fileserver, but is also used by the volserver as an optimization so it +does not need to always go to disk to retrieve volume information for +e.g. the AFSVolListOneVolume or AFSVolListVolumes RPCs. + + -- FSYNC_VOL_QUERY_HDR + +Asks the fileserver to provide the on-disk volume header for the +specified volume, if the fileserver already has it loaded. If the +fileserver does not already know this information, it responds with +SYNC_FAILED with the reason code FSYNC_HDR_NOT_ATTACHED. Otherwise it +responds with a filled-in 'struct VolumeDiskData' in the response +payload. + +This is used by non-fileservers as an optimization during attachment if +we are just reading from the volume and we don't need to 'check out' the +volume from the fileserver (attaching with V_PEEK). If the fileserver +has the header loaded, it avoids needing to hit the disk for the volume +header. + + -- FSYNC_VOL_QUERY_VOP (DAFS only) + +Asks the fileserver to provide information about the current volume +operation that has the volume checked out. If the volume is checked out, +the response payload is a filled-in 'struct FSSYNC_VolOp_info'; +otherwise the command fails with SYNC_FAILED. + +This is useful as a debugging aid, and is also used by the volserver to +determine if a volume should be advertised as 'offline' or 'online'. + + -- FSYNC_VOL_ATTACH + +This is like FSYNC_VOL_ON, but for DAFS forces the volume to become +fully attached (as opposed to preattached). This is used for debugging, +to ensure that a volume is attached and online without needing to +contact the fileserver via e.g. a client. + + -- FSYNC_VOL_FORCE_ERROR (DAFS only) + +This tells the fileserver that there is something wrong with a volume, +and it should be put in an error state or salvaged. + +If the reason code is FSYNC_SALVAGE, the fileserver will potentially +schedule a salvage for the volume. It may or may not actually schedule a +salvage, depending on how many salvages have occurred and other internal +logic; basically, specifying FSYNC_SALVAGE makes the fileserver behave +as if the fileserver itself encountered an error with the volume that +warrants a salvage. + +Non-fileserver programs use this to schedule salvages; they should not +contact the salvageserver directly. Note when a salvage is scheduled as +a result of this command, it is done so in the background; getting a +response from this command does not necessarily mean the salvage has +been scheduled, as it may be deferred until later. + +If the reason code is not FSYNC_SALVAGE, the fileserver will just put +the volume into an error state, and the volume will be inaccessible +until it is salvaged, or forced online. + + -- FSYNC_VOL_LEAVE_OFF + +This 'checks in' a volume back to the fileserver, but tells the +fileserver not to bring the volume back online. This can occur when a +non-fileserver program is done with a volume, but the volume's "blessed" +or "inService" fields are not set; this prevents the fileserver from +trying to attach the volume later, only to find the volume is not +blessed and take the volume offline. + + -- FSYNC_VOL_QUERY_VNODE + +Asks the fileserver for information about specific vnode. This takes a +different command header than other vol ops; it takes a struct +FSSYNC_VnQry_hdr which specifies the volume and vnode requested. The +response payload is a 'struct Vnode' if successful. + +This responds with FSYNC_UNKNOWN_VNID if the fileserver doesn't know +anything about the given vnode. This command will not automatically +attach the associated volume; the volume must be attached before issuing +this command in order to do anything useful. + +This is just a debugging tool, to see what the fileserver thinks about a +particular vnode. + + -- stats FSSYNC commands + +FSSYNC commands involving statistics take a FSSYNC_StatsOp_command +struct as their command and arguments. Some of them use arguments to +specify what stats are requested, which are specified in sop->args, the +union in the FSSYNC_StatsOp_hdr struct. + + -- FSYNC_VOL_STATS_GENERAL + +Retrieves general volume package stats from the fileserver. Response +payload consists of a 'struct VolPkgStats'. + + -- FSYNC_VOL_STATS_VICEP (DAFS only) + +Retrieves per-partition stats from the fileserver for the partition +specified in sop->partName. Response payload consists of a 'struct +DiskPartitionStats64'. + + -- FSYNC_VOL_STATS_HASH (DAFS only) + +Retrieves hash chain stats for the hash bucket specified in +sop->hash_bucket. Response payload consists of a 'struct +VolumeHashChainStats'. + + -- FSYNC_VOL_STATS_HDR (DAFS only) + +Retrieves stats for the volume header cache. Response payload consists +of a 'struct volume_hdr_LRU_stats'. + + -- FSYNC_VOL_STATS_VLRU (DAFS only) + +This is intended to retrieve stats for the VLRU generation specified in +sop->vlru_generation. However, it is not yet implemented and currently +always results in a SYNC_BAD_COMMAND result from the fileserver. diff --git a/src/vol/fssync.h b/src/vol/fssync.h index a7fef29..50a3c37 100644 --- a/src/vol/fssync.h +++ b/src/vol/fssync.h @@ -25,6 +25,9 @@ /** * FSYNC command codes. + * + * If you add more command codes here, be sure to add some documentation + * in doc/arch/fssync.txt. */ enum FSYNCOpCode { FSYNC_VOL_ON = SYNC_COM_CODE_DECL(0), /**< bring Volume online */