add more comments about the roles of fic and fid

3 files changed, 36 insertions, 6 deletions

diff --git a/lib/metadata/metadata-exported.h b/lib/metadata/metadata-exported.h
index 85e5838f1..058135656 100644
--- a/lib/metadata/metadata-exported.h
+++ b/lib/metadata/metadata-exported.h
@@ -366,6 +366,20 @@ struct pv_segment {
  */
 #define FMT_INSTANCE_PRIVATE_MDAS	0x00000008U
 
+
+/*
+ * Each VG has its own fid struct.  The fid for a VG describes where
+ * the metadata for that VG can be found.  The lists hold mda locations.
+ *
+ * label scan finds the metadata locations (devs and offsets) for a VG,
+ * and saves this info in lvmcache vginfo/info lists.
+ *
+ * vg_read() then creates an fid for a given VG, and the mda locations
+ * from lvmcache are copied onto the fid lists.  Those mda locations
+ * are read again by vg_read() to get VG metadata that is used to
+ * create the 'vg' struct.
+ */
+
 struct format_instance {
 	unsigned ref_count;	/* Refs to this fid from VG and PV structs */
 	struct dm_pool *mem;
diff --git a/lib/metadata/metadata.c b/lib/metadata/metadata.c
index 80d1e3821..df9d5608f 100644
--- a/lib/metadata/metadata.c
+++ b/lib/metadata/metadata.c
@@ -3886,19 +3886,30 @@ static struct volume_group *_vg_read(struct cmd_context *cmd,
 	 * A "format instance" is an abstraction for a VG location,
 	 * i.e. where a VG's metadata exists on disk.
 	 *
-	 * An fic/fid pair (format_instance_ctx/format_instance) exists
-	 * for each VG.  The fic/fid is set up by create_instance() to
-	 * describe the VG location.  This happens before the VG metadata
-	 * is assembled into the more familiar struct volume_group "vg".
+	 * An fic (format_instance_ctx) is a temporary struct used
+	 * to create an fid (format_instance).  The fid hangs around
+	 * and is used to create a 'vg' to which it connected (vg->fid).
 	 *
-	 * The fic/fid has one main purpose: to keep track of the metadata
+	 * The 'fic' describes a VG in terms of fmt/name/id.
+	 *
+	 * The 'fid' describes a VG in more detail than the fic,
+	 * holding information about where to find the VG metadata.
+	 *
+	 * The 'vg' describes the VG in the most detail representing
+	 * all the VG metadata.
+	 *
+	 * The fic and fid are set up by create_instance() to describe
+	 * the VG location.  This happens before the VG metadata is
+	 * assembled into the more familiar struct volume_group "vg".
+	 *
+	 * The fid has one main purpose: to keep track of the metadata
 	 * locations for a given VG.  It does this by putting 'mda'
 	 * structs on fid->metadata_areas_in_use, which specify where
 	 * metadata is located on disk.  It gets this information
 	 * (metadata locations for a specific VG) from the command's
 	 * initial label scan.  The info is passed indirectly via
 	 * lvmcache info/vginfo structs, which are created by the
-	 * label scan and then copied into fic/fid by create_instance().
+	 * label scan and then copied into fid by create_instance().
 	 */
 
 	/* create format instance with appropriate metadata area */
diff --git a/lib/metadata/metadata.h b/lib/metadata/metadata.h
index 937945607..145d0428a 100644
--- a/lib/metadata/metadata.h
+++ b/lib/metadata/metadata.h
@@ -179,6 +179,11 @@ void mda_set_ignored(struct metadata_area *mda, unsigned mda_ignored);
 unsigned mda_locns_match(struct metadata_area *mda1, struct metadata_area *mda2);
 struct device *mda_get_device(struct metadata_area *mda);
 
+/*
+ * fic is used to create an fid.  It's used to pass fmt/vgname/vgid args
+ * to create_instance() which creates an fid for the specified vg.
+ */
+
 struct format_instance_ctx {
 	uint32_t type;
 	union {