--- /dev/null
+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.