LU-12885 llapi: use enum llapi_layout_get_flags

For the llapi_layout_get_by_{fd,fid,path,xattr}() functions use a new
enum llapi_layout_get_flags as an argument to make it clear what flags
are passed, rather than a generic "uint32_t flags" argument.

Rename the flags to be consistent between the different functions,
instead of having separate flags for llapi_layout_get_by_xattr() and
add a LLAPI_ prefix to avoid potential namespace conflicts.

Signed-off-by: Andreas Dilger <adilger@whamcloud.com>
Change-Id: I671f1a3b96df4fa93e9529a373ceb450b13ebbe5
Reviewed-on: https://review.whamcloud.com/36524
Reviewed-by: James Simmons <jsimmons@infradead.org>
Tested-by: jenkins <devops@whamcloud.com>
Tested-by: Maloo <maloo@whamcloud.com>
Reviewed-by: Jian Yu <yujian@whamcloud.com>
Reviewed-by: Oleg Drokin <green@whamcloud.com>

diff --git a/lustre/doc/llapi_layout_get_by_fd.3 b/lustre/doc/llapi_layout_get_by_fd.3
index dfd0500..864bf24 100644 (file)
--- a/lustre/doc/llapi_layout_get_by_fd.3
+++ b/lustre/doc/llapi_layout_get_by_fd.3
@@ -6,18 +6,19 @@ obtain the layout of a Lustre file
 .nf
 .B #include <lustre/lustreapi.h>
 .PP
-.BI "struct llapi_layout *llapi_layout_get_by_fd(int "fd ", uint32_t " flags );
+.BI "struct llapi_layout *llapi_layout_get_by_fd(int " fd ,
+.BI "                                     enum llapi_layout_get_flags " flags );
 .PP
 .BI "struct llapi_layout *llapi_layout_get_by_fid(const char *"lustre_path ,
-.BI "                                             const struct lu_fid *"fid ,
-.BI "                                             uint32_t " flags );
+.BI "                                     const struct lu_fid *"fid ,
+.BI "                                     enum llapi_layout_get_flags " flags );
 .PP
 .BI "struct llapi_layout *llapi_layout_get_by_path(const char *"path ,
-.BI "                                              uint32_t " flags );
+.BI "                                     enum llapi_layout_get_flags " flags );
 .PP
 .BI "struct llapi_layout *llapi_layout_get_by_xattr(void *"lov_xattr ,
-.BI "                                               ssize_t " lov_xattr_size ,
-.BI "                                               uint32_t " xattr_flags );
+.BI "                                     ssize_t " lov_xattr_size ,
+.BI "                                     enum llapi_layout_get_flags " flags );
 .fi
 .SH DESCRIPTION
 .PP
@@ -61,9 +62,9 @@ filesystem.
 .PP
 For
 .BR llapi_layout_get_by_fid() ,
-the path named by
+the
 .I lustre_path
-serves to identify the Lustre filesystem containing the file
+argument serves to identify the Lustre filesystem containing the file
 represented by
 .IR fid .
 It is typically the filesystem root, but may also be any path beneath
@@ -85,15 +86,15 @@ or
 .I xattr_flags
 to control how a layout is retrieved.  Currently
 .B llapi_layout_get_by_path()
-accepts only one flag, and
+accepts only one flag, while
 .B llapi_layout_get_by_fd()
 and
 .B llapi_layout_get_by_fid()
-do not accept any flags. The list of flags that can be used in
+do not use any flags. The list of flags that can be used in
 .I flags
 is as follows:
 .TP 5
-.SM LAYOUT_GET_EXPECTED
+.SM LLAPI_LAYOUT_GET_EXPECTED
 Unspecified attribute values are replaced by the literal default values
 that will be assigned when the file is created or first written to.
 A default value is inherited from the parent directory if the attribute
@@ -106,7 +107,7 @@ files.
 By default, layouts report the abstract value
 .B LLAPI_LAYOUT_DEFAULT
 to indicate an unspecified attribute.  Use
-.B LAYOUT_GET_EXPECTED
+.B LLAPI_LAYOUT_GET_EXPECTED
 to discover the expected literal values for new files in a given
 directory.  Do not use it if you need to distinguish between specified
 and unspecified attributes.  The flag has no effect if
@@ -123,30 +124,30 @@ the filesystem default.  The layout of D returned by
 has the abstract stripe size value
 .BR LLAPI_LAYOUT_DEFAULT ,
 since stripe size is unspecified, while
-.B llapi_layout_get_by_path(D, LAYOUT_GET_EXPECTED)
+.B llapi_layout_get_by_path(D, LLAPI_LAYOUT_GET_EXPECTED)
 reports the literal value 1048576.  Both forms report a stripe count
 of 2, since that attribute is specified.
 .PP
-The list of flags that can be used in
-.I xattr_flags
-is as follows:
+The values that can be used by
+.B llapi_layout_get_by_xattr()
+.I flags
+argument is as follows:
 .TP 5
-.SM LLAPI_LXF_CHECK
+.SM LLAPI_LAYOUT_GET_CHECK
 If the
-.B LLAPI_LXF_CHECK
+.B LLAPI_LAYOUT_GET_CHECK
 flag is set, this function will check whether the objects count in lum
 is consistent with the stripe count in lum. This check only apply to
-regular file, so
-.B LLAPI_LXF_CHECK
-flag should be cleared if the xattr belongs to a directory.
+regular files, so it should not be passed if the xattr is a default
+layout from a directory.
 .TP
-.SM LLAPI_LXF_COPY
+.SM LLAPI_LAYOUT_GET_COPY
 If the
-.B LLAPI_LXF_COPY
+.B LLAPI_LAYOUT_GET_COPY
 flag is set, this function will use a temporary buffer for byte swapping
 when necessary, leaving
 .I lov_xattr
-untouched. Otherwise, the byte swapping will be done to the
+unmodified. Otherwise, the byte swapping will be done to the fields of the
 .I lov_xattr
 buffer directly.
 .SH RETURN VALUES

diff --git a/lustre/include/lustre/lustreapi.h b/lustre/include/lustre/lustreapi.h
index d057fc1..78a2e44 100644 (file)
--- a/lustre/include/lustre/lustreapi.h
+++ b/lustre/include/lustre/lustreapi.h
@@ -672,8 +672,18 @@ int llapi_mirror_resync_many(int fd, struct llapi_layout *layout,
  * Flags to control how layouts are retrieved.
  */
 
-/* Replace non-specified values with expected inherited values. */
-#define LAYOUT_GET_EXPECTED 0x1
+enum llapi_layout_get_flags {
+       /** Replace non-specified values with expected inherited values. */
+       LLAPI_LAYOUT_GET_EXPECTED       = 0x0001,
+       /** Use a temporary buffer to swab and return xattrs. */
+       LLAPI_LAYOUT_GET_COPY           = 0x0002,
+       /** Verify xattr contains sane layout values. */
+       LLAPI_LAYOUT_GET_CHECK          = 0x0004,
+};
+/* compatibility macros for old interfaces */
+#define LAYOUT_GET_EXPECTED    LLAPI_LAYOUT_GET_EXPECTED
+#define LLAPI_LXF_COPY         LLAPI_LAYOUT_GET_COPY
+#define LLAPI_LXF_CHECK                LLAPI_LAYOUT_GET_CHECK
 
 /**
  * Return a pointer to a newly-allocated opaque data structure containing
@@ -681,7 +691,8 @@ int llapi_mirror_resync_many(int fd, struct llapi_layout *layout,
  * llapi_layout_free() when it is no longer needed. Failure is indicated
  * by a NULL return value and an appropriate error code stored in errno.
  */
-struct llapi_layout *llapi_layout_get_by_path(const char *path, uint32_t flags);
+struct llapi_layout *llapi_layout_get_by_path(const char *path,
+                                            enum llapi_layout_get_flags flags);
 
 /**
  * Return a pointer to a newly-allocated opaque data type containing the
@@ -690,7 +701,8 @@ struct llapi_layout *llapi_layout_get_by_path(const char *path, uint32_t flags);
  * needed. Failure is indicated by a NULL return value and an
  * appropriate error code stored in errno.
  */
-struct llapi_layout *llapi_layout_get_by_fd(int fd, uint32_t flags);
+struct llapi_layout *llapi_layout_get_by_fd(int fd,
+                                           enum llapi_layout_get_flags flags);
 
 /**
  * Return a pointer to a newly-allocated opaque data type containing the
@@ -704,12 +716,7 @@ struct llapi_layout *llapi_layout_get_by_fd(int fd, uint32_t flags);
  */
 struct llapi_layout *llapi_layout_get_by_fid(const char *path,
                                             const struct lu_fid *fid,
-                                            uint32_t flags);
-
-enum llapi_layout_xattr_flags {
-       LLAPI_LXF_CHECK = 0x0001,
-       LLAPI_LXF_COPY  = 0x0002,
-};
+                                            enum llapi_layout_get_flags flags);
 
 /**
  * Return a pointer to a newly-allocated opaque data type containing the
@@ -719,18 +726,18 @@ enum llapi_layout_xattr_flags {
  * properly. Thus, \a lov_xattr will be modified during the process. If the
  * \a LLAPI_LXF_CHECK flag of \a flags is set, this function will check whether
  * the objects count in lum is consistent with the stripe count in lum. This
- * check only apply to regular file, so \a LLAPI_LXF_CHECK flag should be
- * cleared if the xattr belongs to a directory. If the \a LLAPI_LXF_COPY flag
- * of \a flags is set, this function will use a temporary buffer for byte
- * swapping when necessary, leaving \a lov_xattr untouched. Otherwise, the byte
- * swapping will be done to the \a lov_xattr buffer directly.  The returned
+ * check only apply to regular file, so \a LLAPI_LAYOUT_GET_CHECK flag should
+ * be cleared if the xattr belongs to a directory. If the flag \a
+ * LLAPI_LAYOUT_GET_COPY is set, this function will use a temporary buffer for
+ * byte swapping when necessary, leaving \a lov_xattr untouched. Otherwise, the
+ * byte swapping will be done to the \a lov_xattr buffer directly.  The returned
  * pointer should be freed with llapi_layout_free() when it is no longer
  * needed.  Failure is  * indicated with a NULL return value and an appropriate
  * error code stored in errno.
  */
 struct llapi_layout *llapi_layout_get_by_xattr(void *lov_xattr,
-                                              ssize_t lov_xattr_size,
-                                              uint32_t flags);
+                                            ssize_t lov_xattr_size,
+                                            enum llapi_layout_get_flags flags);
 
 /**
  * Allocate a new layout. Use this when creating a new file with

diff --git a/lustre/utils/liblustreapi_layout.c b/lustre/utils/liblustreapi_layout.c
index 82e3c4a..fb51e1d 100644 (file)
--- a/lustre/utils/liblustreapi_layout.c
+++ b/lustre/utils/liblustreapi_layout.c
@@ -434,14 +434,14 @@ static bool llapi_layout_lum_valid(struct lov_user_md *lum, int lum_size)
  *
  * \param[in] lov_xattr                LOV user metadata xattr to copy data from
  * \param[in] lov_xattr_size   size the lov_xattr_size passed in
- * \param[in] flags            bitwise-or'd flags to control the behavior
+ * \param[in] flags            flags to control how layout is retrieved
  *
  * \retval             valid llapi_layout pointer on success
  * \retval             NULL if memory allocation fails
  */
 struct llapi_layout *llapi_layout_get_by_xattr(void *lov_xattr,
-                                              ssize_t lov_xattr_size,
-                                              uint32_t flags)
+                                             ssize_t lov_xattr_size,
+                                             enum llapi_layout_get_flags flags)
 {
        struct lov_user_md *lum = lov_xattr;
        struct lov_comp_md_v1 *comp_v1 = NULL;
@@ -463,7 +463,7 @@ struct llapi_layout *llapi_layout_get_by_xattr(void *lov_xattr,
        }
 
 #if __BYTE_ORDER == __BIG_ENDIAN
-       if (flags & LLAPI_LXF_COPY) {
+       if (flags & LLAPI_LAYOUT_GET_COPY) {
                lum = malloc(lov_xattr_size);
                if (lum == NULL) {
                        errno = ENOMEM;
@@ -475,7 +475,12 @@ struct llapi_layout *llapi_layout_get_by_xattr(void *lov_xattr,
 
        llapi_layout_swab_lov_user_md(lum, lov_xattr_size);
 
-       if ((flags & LLAPI_LXF_CHECK) &&
+#if LUSTRE_VERSION_CODE > OBD_OCD_VERSION(2, 16, 53, 0)
+#define LLAPI_LXF_CHECK_OLD 0x0001
+       if (flags & LLAPI_LXF_CHECK_OLD)
+               flags = (flags & ~LLAPI_LXF_CHECK_OLD) | LLAPI_LAYOUT_GET_CHECK;
+#endif
+       if ((flags & LLAPI_LAYOUT_GET_CHECK) &&
            !llapi_layout_lum_valid(lum, lov_xattr_size)) {
                errno = EBADSLT;
                goto out;
@@ -921,7 +926,8 @@ static bool is_any_specified(const struct llapi_layout *layout)
  * \retval     valid llapi_layout pointer on success
  * \retval     NULL if an error occurs
  */
-struct llapi_layout *llapi_layout_get_by_fd(int fd, uint32_t flags)
+struct llapi_layout *llapi_layout_get_by_fd(int fd,
+                                           enum llapi_layout_get_flags flags)
 {
        size_t lum_len;
        struct lov_user_md *lum;
@@ -951,7 +957,7 @@ struct llapi_layout *llapi_layout_get_by_fd(int fd, uint32_t flags)
                goto out;
 
        layout = llapi_layout_get_by_xattr(lum, bytes_read,
-               S_ISDIR(st.st_mode) ? 0 : LLAPI_LXF_CHECK);
+                       S_ISDIR(st.st_mode) ? 0 : LLAPI_LAYOUT_GET_CHECK);
 out:
        free(lum);
        return layout;
@@ -1049,7 +1055,7 @@ static struct llapi_layout *llapi_layout_expected(const char *path)
 /**
  * Get the striping layout for the file at \a path.
  *
- * If \a flags contains LAYOUT_GET_EXPECTED, substitute
+ * If \a flags contains LLAPI_LAYOUT_GET_EXPECTED, substitute
  * expected inherited attribute values for unspecified attributes. See
  * llapi_layout_expected().
  *
@@ -1059,13 +1065,14 @@ static struct llapi_layout *llapi_layout_expected(const char *path)
  * \retval     valid llapi_layout pointer on success
  * \retval     NULL if an error occurs
  */
-struct llapi_layout *llapi_layout_get_by_path(const char *path, uint32_t flags)
+struct llapi_layout *llapi_layout_get_by_path(const char *path,
+                                             enum llapi_layout_get_flags flags)
 {
        struct llapi_layout *layout = NULL;
        int fd;
        int tmp;
 
-       if (flags & LAYOUT_GET_EXPECTED)
+       if (flags & LLAPI_LAYOUT_GET_EXPECTED)
                return llapi_layout_expected(path);
 
        fd = open(path, O_RDONLY);
@@ -1091,7 +1098,7 @@ struct llapi_layout *llapi_layout_get_by_path(const char *path, uint32_t flags)
  */
 struct llapi_layout *llapi_layout_get_by_fid(const char *lustre_dir,
                                             const struct lu_fid *fid,
-                                            uint32_t flags)
+                                            enum llapi_layout_get_flags flags)
 {
        int fd;
        int tmp;