| Message ID | 20181109202157.5565-1-agrover@redhat.com (mailing list archive) |
|---|---|
| State | Deferred, archived |
| Delegated to: | Mike Snitzer |
| Headers | show |
| Series | dm integrity: Document size and format of superblock fields | expand |
On 11/9/18 12:21 PM, Andy Grover wrote: > 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. 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 :) -- dm-devel mailing list dm-devel@redhat.com https://www.redhat.com/mailman/listinfo/dm-devel
On 13/11/2018 01:23, Andy Grover wrote: > On 11/9/18 12:21 PM, Andy Grover wrote: >> 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.> > 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. 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+. > 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. -- dm-devel mailing list dm-devel@redhat.com https://www.redhat.com/mailman/listinfo/dm-devel
You 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 On Fri, 9 Nov 2018, Andy Grover wrote: > 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. > > Signed-off-by: Andy Grover <agrover@redhat.com> > --- > Documentation/device-mapper/dm-integrity.txt | 26 ++++++++++++-------- > 1 file changed, 16 insertions(+), 10 deletions(-) > > diff --git a/Documentation/device-mapper/dm-integrity.txt b/Documentation/device-mapper/dm-integrity.txt > index 297251b0d2d5..3d28328f16c1 100644 > --- a/Documentation/device-mapper/dm-integrity.txt > +++ b/Documentation/device-mapper/dm-integrity.txt > @@ -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 > -- > 2.17.2 > -- dm-devel mailing list dm-devel@redhat.com https://www.redhat.com/mailman/listinfo/dm-devel
diff --git a/Documentation/device-mapper/dm-integrity.txt b/Documentation/device-mapper/dm-integrity.txt index 297251b0d2d5..3d28328f16c1 100644 --- a/Documentation/device-mapper/dm-integrity.txt +++ b/Documentation/device-mapper/dm-integrity.txt @@ -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
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. Signed-off-by: Andy Grover <agrover@redhat.com> --- Documentation/device-mapper/dm-integrity.txt | 26 ++++++++++++-------- 1 file changed, 16 insertions(+), 10 deletions(-)