^^^^^^^^^^^^^^^^^^^^
[[struct-lov-mds-md]]
-The 'lov_mds_md' structure is a Lock Value Block (LVB) for layout
-locks. In replies to lock requests and other situations requiring
+The 'lov_mds_md' structure contains the layout of a single file.
+In replies to lock requests and other situations requiring
layout information from an MDT the 'lov_mds_md' information provides
-details about the layout of a file across the OSTs.
+details about the layout of a file across the OSTs. There may be
+different types of layouts for different files, either 'lov_mds_md_v1'
+or 'lov_mds_md_v3' as of Lustre 2.7, though they are very similar in
+structure.
----
-struct lov_mds_md {
+struct lov_mds_md_v1 {
__u32 lmm_magic;
__u32 lmm_pattern;
struct ost_id lmm_oi;
__u16 lmm_layout_gen;
struct lov_ost_data_v1 lmm_objects[0];
};
+
+struct lov_mds_md_v3 {
+ __u32 lmm_magic;
+ __u32 lmm_pattern;
+ struct ost_id lmm_oi;
+ __u32 lmm_stripe_size;
+ __u16 lmm_stripe_count;
+ __u16 lmm_layout_gen;
+ char lmm_pool_name[16];
+ struct lov_ost_data_v1 lmm_objects[0];
+};
----
-The 'lmm_magic' field is filled in with the value LOV_MAGIC
-(0x0BD10BD0) when the structure is in use. If the structure is in a
+The 'lmm_magic' field is filled in with the magic value that describes
+the type of layout in use for a particular file. The rest of the layout
+structure may vary depending on the magic value, but the 'lmm_magic'
+value must be the first member of any valid file layout. The values
+LOV_MAGIC_V1 (0x0BD10BD0) and LOV_MAGIC_V3 (0x0BD30BD0) are most
+commonly used when the structure is in use. If the structure is in a
buffer of an RPC without the magic number in place, then the rest of
the structure is ignored.
-The 'lmm_pattern' field is only ever set to LOV_PATTERN_RAID0
-(0x001).
+The 'lmm_pattern' field describes the layout pattern within a particular
+LOV_MAGIC layout type. Currently in Lustre 2.7 the most common pattern
+is LOV_PATTERN_RAID0 (0x001). The high 16 bits of the 'lmm_pattern' field
+may also contain flags that modify the layout. LOV_PATTERN_F_HOLE means
+that there is a hole (missing object) within the layout, which is normally
+caused by corruption or loss of the file layout that had to be rebuilt
+by LFSCK. LOV_PATTERN_F_RELEASED is used by HSM to indicate that the
+file data is not resident in the filesystem, but rather in an external
+archive, so the layout is only a stub that describes the layout to use
+when the file is restored.
-The 'lmm_oi' field gives the LOV object ID for the first OST of the
-layout. This is the OST where striping will begin.
+The 'lmm_oi' field gives the identifier of the MDT object to which this
+file belongs. See <<struct-ost-id>> for more details.
-The 'lmm_stripe_size' field give the stripe size for the object. This
-is how many bytes will be on a particular OST before going to the next
-stripe.
+The 'lmm_stripe_size' field give the stripe size for the layout in bytes.
+This is how many bytes will be on a particular OST object before going
+to the next stripe.
-The 'lmm_stripe_count' field gives how many OSTs the file is striped
+The 'lmm_stripe_count' field gives how many OST objects the file is striped
over.
-The 'lmm_layout_gen' field ges updated as the layout of the obeject is
-updated. This way out-of-date references to the layout can be
-recognized.
+The 'lmm_layout_gen' field is updated as the layout of the obeject is
+updated. If the 'lmm_layout_gen' is modified, then clients can detect
+the layout has changed when refreshing the layout after having lost the
+layout lock.
+
+The 'lmm_pool_name' field is only in LOV_MAGIC_V3 layouts, and contains
+the name of the OST pool used during the creation of the layout.
+
+For instantiated layouts, 'lmm_objects' array contains 'lmm_stripe_count'
+'lov_ost_data_v1' structures with the per-stripe data for each OST object
+in the layout. For uninstantiated layout templates, there will not be any
+entries in the 'lmm_objects' array, which can be determined by the overall
+layout size.
+
+----
+struct lov_ost_data_v1 { /* per-stripe data structure (little-endian)*/
+ struct ost_id l_ost_oi; /* OST object ID */
+ __u32 l_ost_gen; /* generation of this l_ost_idx */
+ __u32 l_ost_idx; /* OST index in LOV (lov_tgt_desc->tgts) */
+};
+----
+[[struct-lov-ost-data-v1]]
-The 'lmm_objects' array gives per-stripe data for more complex
-(non-uniform) layouts.
+The 'lov_ost_data_v1' structure is used for both LOV_MAGIC_V1 and
+LOV_MAGIC_V3 types to describe the OST objects allocated to this
+layout, one per object.
+'l_ost_id' identifies the object on the OST specified by 'l_ost_idx'.
+It may contain a OST object ID or a FID as described in <<struct-ost-id>>.
+The 'l_ost_gen' field is currently unused.