design: document new name-value logged attribute variants
In preparation for parent pointers, we added a few new opcodes for
logged extended attribute updates. Document them now.
Signed-off-by: Darrick J. Wong <djwong@kernel.org>
diff --git a/design/XFS_Filesystem_Structure/journaling_log.asciidoc b/design/XFS_Filesystem_Structure/journaling_log.asciidoc
index daf9b22..c91fbb6 100644
--- a/design/XFS_Filesystem_Structure/journaling_log.asciidoc
+++ b/design/XFS_Filesystem_Structure/journaling_log.asciidoc
@@ -730,10 +730,21 @@
.Extended attribute update log intent types
[options="header"]
|=====
-| Value | Description
-| +XFS_ATTRI_OP_FLAGS_SET+ | Set a key/value pair.
-| +XFS_ATTRI_OP_FLAGS_REMOVE+ | Remove a key/value pair.
-| +XFS_ATTRI_OP_FLAGS_REPLACE+ | Replace one key/value pair with another.
+| Value | Description
+| +XFS_ATTRI_OP_FLAGS_SET+ | Associate an attribute name with the
+given value, creating an entry for the name if necessary.
+| +XFS_ATTRI_OP_FLAGS_REMOVE+ | Remove an attribute name and any
+value associated with it.
+| +XFS_ATTRI_OP_FLAGS_REPLACE+ | Remove any value associated with an
+attribute name, then associate the name with the given value.
+| +XFS_ATTRI_OP_FLAGS_NVREMOVE+ | Remove the specific name and value
+from the attribute structure. The name and value must already exist.
+| +XFS_ATTRI_OP_FLAGS_NVSET+ | Associate an attribute name with the
+given value. The name and value must not exist in the attribute structure.
+A name associated with a different value will not be removed.
+| +XFS_ATTRI_OP_FLAGS_NVREPLACE+ | Remove a specific name and value from
+the attribute structure, then associate a specific name with a given value.
+The two names and values need not be the same.
|=====
The ``extended attribute update intent'' operation comes first; it tells the
@@ -747,11 +758,17 @@
struct xfs_attri_log_format {
uint16_t alfi_type;
uint16_t alfi_size;
- uint32_t __pad;
+ uint32_t alfi_new_value_len;
uint64_t alfi_id;
uint64_t alfi_ino;
uint32_t alfi_op_flags;
- uint32_t alfi_name_len;
+ union {
+ uint32_t alfi_name_len;
+ struct {
+ uint16_t alfi_old_name_len;
+ uint16_t alfi_new_name_len;
+ };
+ };
uint32_t alfi_value_len;
uint32_t alfi_attr_filter;
};
@@ -764,6 +781,11 @@
*alfi_size*::
Size of this log item. Should be 1.
+*alfi_new_value_len*::
+For NVREPLACE, this is the length of the new xattr value, and +alfi_value_len+
+contains the length of the old xattr value.
+For all other opcodes, this field must be zero.
+
*alfi_id*::
A 64-bit number that binds the corresponding ATTRD log item to this ATTRI log
item.
@@ -778,6 +800,13 @@
*alfi_name_len*::
Length of the name of the extended attribute. This must not be zero.
The attribute name itself is captured in the next log item.
+This field is not defined for the NVREPLACE opcode.
+
+*alfi_old_name_len*::
+For NVREPLACE, this is the length of the old name.
+
+*alfi_new_name_len*::
+For NVREPLACE, this is the length of the new name.
*alfi_value_len*::
Length of the value of the extended attribute. This must be zero for remove
@@ -789,6 +818,25 @@
Attribute namespace filter flags. This must be one of +ATTR_ROOT+,
+ATTR_SECURE+, or +ATTR_INCOMPLETE+.
+For a SET or REPLACE opcode, there should be two regions after the ATTRI intent
+item. The first region contains the attribute name and the second contains the
+attribute value.
+
+For a REMOVE opcode, there should only be one region after the ATTRI intent
+item, and it will contain the attribute name.
+
+For an NVSET or NVREMOVE opcode, there should be one or two regions after the
+ATTRI intent item. The first region contains the attribute name. The second
+region, if present, contains the attribute value.
+
+For an NVREPLACE opcode, there should be between two and four regions after the
+ATTRI intent item. The first region contains the attribute name to remove.
+The second region contains the attribute name to create. If +alfi_value_len+
+is nonzero, the third region contains the attribute value to remove. If
++alfi_new_value_len+ is nonzero, the next region seen contains the attribute
+value to create. This could be the third region if there was no value to
+remove, or it could be the fourth region.
+
[[ATTRD_Log_Item]]
=== Completion of Extended Attribute Updates
