design: document new name-value logged attribute variantspptrs-attr-nvlookups_2023-12-31pptrs-attr-nvlookups

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>

1 files changed, 54 insertions, 6 deletions

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 @@ of file block mapping operation we want.
 .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 @@ through the complex update will be replayed fully during log recovery.
 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 @@ order, not big-endian like the rest of XFS.
 *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 @@ The operation being performed.  The lower byte must be one of the
 *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 @@ name.
 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