From c78bbe7c886330f1dbafafe774b4be2dffdde048 Mon Sep 17 00:00:00 2001
From: Natalia Portillo <claunia@claunia.com>
Date: Fri, 1 Aug 2025 04:24:16 +0100
Subject: [PATCH] [spec] Update deduplication table descriptions for clarity
 and accuracy

---
 docs/spec/blocks/ddt2.adoc   | 13 +++++++++----
 docs/spec/blocks/header.adoc |  2 ++
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/docs/spec/blocks/ddt2.adoc b/docs/spec/blocks/ddt2.adoc
index 238b90b..83b7a80 100644
--- a/docs/spec/blocks/ddt2.adoc
+++ b/docs/spec/blocks/ddt2.adoc
@@ -57,13 +57,18 @@ It starts with the following header.
 
 |uint8_t
 |1 byte
-|alignment
-|Shift of alignment of all blocks in the image. This must be the same in all deduplication tables and subtables.
+|blockAlignmentShift
+|Determines block alignment boundaries using the formula 2 << blockAlignmentShift.
 
 |uint8_t
 |1 byte
-|shift
-|The shift used to calculate the position of a sector in a data block pointed by this table, or how many sectors are pointed by the next level.
+|dataShift
+|Determines the maximum number of data items in a block using the formula 2 << dataShift.
+
+|uint8_t
+|1 byte
+|tableShift
+|Shift used to calculate the number of sectors in a deduplication table entry, using the formula 2 << tableShift.
 
 |uint8_t
 |1 byte
diff --git a/docs/spec/blocks/header.adoc b/docs/spec/blocks/header.adoc
index 59cbd59..e40a281 100644
--- a/docs/spec/blocks/header.adoc
+++ b/docs/spec/blocks/header.adoc
@@ -71,6 +71,8 @@ A bump indicates potential breaking changes.
 
 Length is defined by `GUID_SIZE`.
 | blockAlignmentShift | uint8_t | Determines block alignment boundaries using the formula 2 << blockAlignmentShift.
+| dataShift | uint8_t | Determines the maximum number of data items in a block using the formula 2 << dataShift.
+| tableShift | uint8_t | Shift used to calculate the number of sectors in a deduplication table entry, using the formula 2 << tableShift.
 | featureCompatible | uint64_t | Bitmask of features that, even if not implemented, still allow reading and writing the image.
 
 | featureCompatibleRo | uint64_t | Bitmask of features that allow read-only processing of the image if unsupported.