struct_lu_fid.txt

   1 Lustre File Identifiers
   2 ^^^^^^^^^^^^^^^^^^^^^^^
   3 [[struct-lu-fid]]
   4
   5 Each resource stored on a target is assigned an identifier that is
   6 unique to that resource.
   7
   8 [source,c]
   9 --------
  10 struct lu_fid {
  11         __u64 f_seq;
  12         __u32 f_oid;
  13         __u32 f_ver;
  14 };
  15 --------
  16
  17 A file identifier ('FID') is a 128-bit numbers that uniquely identifies a
  18 single file or directory on an MDTs or OSTs within a single Lustre file
  19 system. The FID for a Lustre file or directory is the FID from the
  20 corresponding MDT entry for the file. Each of the data resource for that
  21 file will also have a FID for each corresponding OST resource on which the
  22 file stores data.
  23
  24 The 'f_seq' field holds the sequence number, or SEQ, and is used in
  25 conjunction with the 'FID location database' (FLDB) to
  26 determine on which target the resource is located.  All resources with the
  27 same 'f_seq' value will be on the same target. A target can have more
  28 than one 'f_seq' value assigned to it.
  29
  30 The 'f_oid' field holds the unique 'object identifier' (OID) within the
  31 sequence to identify a particular object.
  32
  33 The 'f_ver' value identifies which version of a resource is being
  34 identified, in the event that the resource is being updated, and
  35 different hosts might be referring to different versions of the same
  36 resource. It has never been used as of Lustre 2.8.
  37
  38 [source,c]
  39 ----
  40 enum fid_seq {
  41         FID_SEQ_OST_MDT0        = 0,
  42         FID_SEQ_LLOG            = 1, /* unnamed llogs */
  43         FID_SEQ_ECHO            = 2,
  44         FID_SEQ_UNUSED_START    = 3,
  45         FID_SEQ_UNUSED_END      = 9,
  46         FID_SEQ_LLOG_NAME       = 10, /* named llogs */
  47         FID_SEQ_RSVD            = 11,
  48         FID_SEQ_IGIF            = 12,
  49         FID_SEQ_IGIF_MAX        = 0x0ffffffffULL,
  50         FID_SEQ_IDIF            = 0x100000000ULL,
  51         FID_SEQ_IDIF_MAX        = 0x1ffffffffULL,
  52         /* Normal FID sequence starts from this value, i.e. 1<<33 */
  53         FID_SEQ_START           = 0x200000000ULL,
  54         /* sequence for local pre-defined FIDs listed in local_oid */
  55         FID_SEQ_LOCAL_FILE      = 0x200000001ULL,
  56         FID_SEQ_DOT_LUSTRE      = 0x200000002ULL,
  57         /* sequence is used for local named objects FIDs generated
  58          * by local_object_storage library */
  59         FID_SEQ_LOCAL_NAME      = 0x200000003ULL,
  60         /* Because current FLD will only cache the fid sequence, instead
  61          * of oid on the client side, if the FID needs to be exposed to
  62          * clients sides, it needs to make sure all of fids under one
  63          * sequence will be located in one MDT. */
  64         FID_SEQ_SPECIAL         = 0x200000004ULL,
  65         FID_SEQ_QUOTA           = 0x200000005ULL,
  66         FID_SEQ_QUOTA_GLB       = 0x200000006ULL,
  67         FID_SEQ_ROOT            = 0x200000007ULL,  /* Located on MDT0 */
  68         FID_SEQ_LAYOUT_RBTREE   = 0x200000008ULL,
  69         /* sequence is used for update logs of cross-MDT operation */
  70         FID_SEQ_UPDATE_LOG      = 0x200000009ULL,
  71         /* Sequence is used for the directory under which update logs
  72          * are created. */
  73         FID_SEQ_UPDATE_LOG_DIR  = 0x20000000aULL,
  74         FID_SEQ_NORMAL          = 0x200000400ULL,
  75         FID_SEQ_LOV_DEFAULT     = 0xffffffffffffffffULL
  76 };
  77 ----
  78
  79 There are several reserved ranges of FID sequence values, to allow for
  80 interoperability with older Lustre filesystems, to identify "well known"
  81 objects for internal or external use, as well as for future expansion.
  82
  83 The 'FID_SEQ_OST_MDT0' (0x0) range is reserved for OST objects created
  84 by MDT0 in non-DNE filesystems.  Since all such OST objects used an
  85 'f_seq' value of zero these FIDs are not unique across the filesystem,
  86 but the reservation of 'FID_SEQ_OST_MDT0' allows these FIDs to co-exist
  87 with other FIDs in the same 128-bit identifier space.
  88
  89 The 'FID_SEQ_LLOG' (0x1) range is reserved for unnamed Lustre log (llog)
  90 files, used only internally on the MDS since Lustre 2.4, but previously
  91 exposed over the network.
  92
  93 The 'FID_SEQ_ECHO' (0x2) range is used for temporary objects for
  94 testing purposes such as obdfiler-survey.
  95
  96 The 'FID_SEQ_LLOG_NAME' (0x10) range is used for named llog files such
  97 as configuration logs and the ChangeLog.
  98
  99 The 'FID_SEQ_IGIF' (0xb-0xffffffff) range is reserved for 'inode and
 100 generation in FID' (IGIF) inodes allocated by MDSes before Lustre 2.0.
 101 This corresponds to the 4 billion maximum inode number that could be
 102 allocated for such filesystems.  The 'f_oid' field for IGIF FIDs
 103 contains the inode version number, and as such there is normally only
 104 a single object for each 'f_seq' value.
 105
 106 The 'FID_SEQ_IDIF' (0x100000000-0x1fffffffff) range is reserved for
 107 mapping OST objects that were created by MDT0 using 'FID_SEQ_OST_MDT0'
 108 to filesystem-unique FIDs.  The second 16-bit field (bits 16-31) of the
 109 'f_seq' field contains the OST index (0-65535).  The low 16-bit field
 110 (bits 0-15) of 'f_seq' contains the high (bits 32-47) bits of the OST
 111 object ID, and the 32-bit 'f_oid' field contains the low 32 bits of
 112 the OST object ID.
 113
 114 The 'FID_SEQ_LOCAL_FILE' (0x200000001) range is reserved for "well
 115 known" objects internal to the server and is not exposed to the network.
 116
 117 The 'FID_SEQ_DOT_LUSTRE' (0x200000002) range is reserved for files
 118 under the hidden ".lustre" directory in the root of the filesystem.
 119
 120 The 'FID_SEQ_LOCAL_NAME' (0x200000003) range is reserved for objects
 121 internal to the server that are allocated by name.
 122
 123 The 'FID_SEQ_NORMAL' (0x200000400+) range is used for normal object
 124 identifiers.  These objects are visible in the namespace if allocated
 125 by an MDT, or may be OST objects.