dm integrity: Document size and format of superblock fields
Subsystems (2)
PATCH 1/1 dm integrity: Document size and format of superblock fields
As mentioned elsewhere in dm-integrity.txt, creating a new integrity device requires creating a small integrity device on top of the base device that formats the base device, reading the provided data sectors out of the superblock, and then recreating the integrity device with the correct size. For this, userspace must know the offset, length, and endianness of the provided_data_sectors field in the superblock.
Document all fields mentioned in the txt to include this, based on struct superblock in dm-integrity.c. Extra fields in struct superblock not already mentioned in the txt remain undocumented.
--- Documentation/device-mapper/dm-integrity.txt | 26 ++++++++++++-------- 1 file changed, 16 insertions(+), 10 deletions(-)
Documentation/device-mapper/dm-integrity.txt +16 -10
@@ -158,16 +158,22 @@ The layout of the formatted block device: storing LUKS metadata or for other purpose), the size of the reserved area is specified in the target arguments * superblock (4kiB) - * magic string - identifies that the device was formatted - * version - * log2(interleave sectors) - * integrity tag size - * the number of journal sections - * provided data sectors - the number of sectors that this target - provides (i.e. the size of the device minus the size of all - metadata and padding). The user of this target should not send - bios that access data beyond the "provided data sectors" limit. - * flags - a flag is set if journal_mac is used + +offset and length in bytes. All values little-endian. + +offset length description +0 8 magic string - identifies that the device was formatted +8 1 version +9 1 log2(interleave sectors) +10 2 integrity tag size +12 4 the number of journal sections +16 8 provided data sectors - the number of sectors that this + target provides (i.e. the size of the device minus the size of + all metadata and padding). The user of this target should not + send bios that access data beyond the "provided data sectors" + limit. +24 4 flags - a flag is set if journal_mac is used + * journal The journal is divided into sections, each section contains: * metadata area (4kiB), it contains journal entries
Signature · 1 line
2.17.2
Quoted 10 lines · Andy Grover
As mentioned elsewhere in dm-integrity.txt, creating a new integrity device requires creating a small integrity device on top of the base device that formats the base device, reading the provided data sectors out of the superblock, and then recreating the integrity device with the correct size. For this, userspace must know the offset, length, and endianness of the
provided_data_sectorsfield in the superblock.Document all fields mentioned in the txt to include this, based on struct superblock in
dm-integrity.c. Extra fields in struct superblock not already mentioned in the txt remain undocumented.
In 4.19 I just noticed provided_data_sectors is now included in dm status. I'm assuming that is now the preferred way for userspace to discover this value? Thus making reading it from the on-disk superblock unnecessary, and thus *documenting* the superblock format unnecessary. Sounds good.
So please disregard this patch, although some different documentation changes are probably now needed.
Thanks -- Regards -- Andy
p.s. I'd just run across an issue where creating an integrity device on a loopback device would result in the superblock still reading as all zeroes. Another reason to do it the new way :)
Quoted 8 lines · Andy Grover
Quoted 7 lines · Andy Grover
As mentioned elsewhere in dm-integrity.txt, creating a new integrity device requires creating a small integrity device on top of the base device that formats the base device, reading the provided data sectors out of the superblock, and then recreating the integrity device with the correct size. For this, userspace must know the offset, length, and endianness of the
provided_data_sectorsfield in the superblock.
Quoted 8 lines
Quoted 3 lines
Document all fields mentioned in the txt to include this, based on struct superblock in
dm-integrity.c. Extra fields in struct superblock not already mentioned in the txt remain undocumented.>In 4.19 I just noticed
provided_data_sectorsis now included in dm status. I'm assuming that is now the preferred way for userspace to discover this value? Thus making reading it from the on-disk superblock unnecessary, and thus *documenting* the superblock format unnecessary. Sounds good.
Yes, I think Mikulas added this for this reason. We still read superblock in integritysetup to be compatible with the older targets, but you should not need it with 4.19+.
Quoted 2 lines
So please disregard this patch, although some different documentation changes are probably now needed.
Actually, meta_device option is not documented at all, and new status line is undocumented as well (I can send patch for this later).
Anyway, I have another page that describes dm-integrity options (maintaining this while adding options to integritysetup, similar page exists for DMcrypt and DMverity)
https://gitlab.com/cryptsetup/cryptsetup/wikis/DMIntegrity
m.
Mikulas Patocka
maintainerYou can change it - though I expect that anyone who will want to parse the superblock will read the file dm-integrity.c anyway.
There's also a new field recalc_sector that says where to resume automatic recalculation.
Mikulas
Quoted 56 lines · Andy Grover
As mentioned elsewhere in dm-integrity.txt, creating a new integrity device requires creating a small integrity device on top of the base device that formats the base device, reading the provided data sectors out of the superblock, and then recreating the integrity device with the correct size. For this, userspace must know the offset, length, and endianness of the
provided_data_sectorsfield in the superblock.Document all fields mentioned in the txt to include this, based on struct superblock in
dm-integrity.c. Extra fields in struct superblock not already mentioned in the txt remain undocumented.Signed-off-by Andy Grover <[email protected]>--- Documentation/device-mapper/dm-integrity.txt | 26 ++++++++++++-------- 1 file changed, 16 insertions(+), 10 deletions(-)Documentation/device-mapper/dm-integrity.txt +16
-10@@ -158,16 +158,22 @@ The layout of the formatted block device: storing LUKS metadata or for other purpose), the size of the reserved area is specified in the target arguments * superblock (4kiB) - * magic string - identifies that the device was formatted - * version - * log2(interleave sectors) - * integrity tag size - * the number of journal sections - * provided data sectors - the number of sectors that this target - provides (i.e. the size of the device minus the size of all - metadata and padding). The user of this target should not send - bios that access data beyond the "provided data sectors" limit. - * flags - a flag is set if journal_mac is used + +offset and length in bytes. All values little-endian. + +offset length description +0 8 magic string - identifies that the device was formatted +8 1 version +9 1 log2(interleave sectors) +10 2 integrity tag size +12 4 the number of journal sections +16 8 provided data sectors - the number of sectors that this + target provides (i.e. the size of the device minus the size of + all metadata and padding). The user of this target should not + send bios that access data beyond the "provided data sectors" + limit. +24 4 flags - a flag is set if journal_mac is used + * journal The journal is divided into sections, each section contains: * metadata area (4kiB), it contains journal entriesSignature · 1 line
2.17.2