[PATCH] Export MDRAID bitmap on disk structure in UAPI header file

[PATCH] Export MDRAID bitmap on disk structure in UAPI header file

[Tomas Mudrunka]

When working on software that manages MD RAID disks from
userspace. Currently provided headers only contain MD superblock.
That is not enough to fully populate MD RAID metadata.
Therefore this patch adds bitmap superblock as well.

Signed-off-by: Tomas Mudrunka <tomas.mudrunka@gmail.com>
---
 drivers/md/md-bitmap.h         | 42 +-------------------------------
 include/uapi/linux/raid/md_p.h | 44 +++++++++++++++++++++++++++++++++-
 2 files changed, 44 insertions(+), 42 deletions(-)

diff --git a/drivers/md/md-bitmap.h b/drivers/md/md-bitmap.h
index 662e6fc14..6050d422b 100644
--- a/drivers/md/md-bitmap.h
+++ b/drivers/md/md-bitmap.h
@@ -7,7 +7,7 @@
 #ifndef BITMAP_H
 #define BITMAP_H 1
 
-#define BITMAP_MAGIC 0x6d746962
+#include <linux/raid/md_p.h>
 
 typedef __u16 bitmap_counter_t;
 #define COUNTER_BITS 16
@@ -18,46 +18,6 @@ typedef __u16 bitmap_counter_t;
 #define RESYNC_MASK ((bitmap_counter_t) (1 << (COUNTER_BITS - 2)))
 #define COUNTER_MAX ((bitmap_counter_t) RESYNC_MASK - 1)
 
-/* use these for bitmap->flags and bitmap->sb->state bit-fields */
-enum bitmap_state {
-	BITMAP_STALE	   = 1,  /* the bitmap file is out of date or had -EIO */
-	BITMAP_WRITE_ERROR = 2, /* A write error has occurred */
-	BITMAP_HOSTENDIAN  =15,
-};
-
-/* the superblock at the front of the bitmap file -- little endian */
-typedef struct bitmap_super_s {
-	__le32 magic;        /*  0  BITMAP_MAGIC */
-	__le32 version;      /*  4  the bitmap major for now, could change... */
-	__u8  uuid[16];      /*  8  128 bit uuid - must match md device uuid */
-	__le64 events;       /* 24  event counter for the bitmap (1)*/
-	__le64 events_cleared;/*32  event counter when last bit cleared (2) */
-	__le64 sync_size;    /* 40  the size of the md device's sync range(3) */
-	__le32 state;        /* 48  bitmap state information */
-	__le32 chunksize;    /* 52  the bitmap chunk size in bytes */
-	__le32 daemon_sleep; /* 56  seconds between disk flushes */
-	__le32 write_behind; /* 60  number of outstanding write-behind writes */
-	__le32 sectors_reserved; /* 64 number of 512-byte sectors that are
-				  * reserved for the bitmap. */
-	__le32 nodes;        /* 68 the maximum number of nodes in cluster. */
-	__u8 cluster_name[64]; /* 72 cluster name to which this md belongs */
-	__u8  pad[256 - 136]; /* set to zero */
-} bitmap_super_t;
-
-/* notes:
- * (1) This event counter is updated before the eventcounter in the md superblock
- *    When a bitmap is loaded, it is only accepted if this event counter is equal
- *    to, or one greater than, the event counter in the superblock.
- * (2) This event counter is updated when the other one is *if*and*only*if* the
- *    array is not degraded.  As bits are not cleared when the array is degraded,
- *    this represents the last time that any bits were cleared.
- *    If a device is being added that has an event count with this value or
- *    higher, it is accepted as conforming to the bitmap.
- * (3)This is the number of sectors represented by the bitmap, and is the range that
- *    resync happens across.  For raid1 and raid5/6 it is the size of individual
- *    devices.  For raid10 it is the size of the array.
- */
-
 struct md_bitmap_stats {
 	u64		events_cleared;
 	int		behind_writes;
diff --git a/include/uapi/linux/raid/md_p.h b/include/uapi/linux/raid/md_p.h
index 5a43c23f5..8131e7713 100644
--- a/include/uapi/linux/raid/md_p.h
+++ b/include/uapi/linux/raid/md_p.h
@@ -1,7 +1,7 @@
 /* SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note */
 /*
    md_p.h : physical layout of Linux RAID devices
-          Copyright (C) 1996-98 Ingo Molnar, Gadi Oxman
+          Copyright (C) 1996-98 Ingo Molnar, Gadi Oxman, Peter T. Breuer
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -426,4 +426,46 @@ struct ppl_header {
 	struct ppl_header_entry entries[PPL_HDR_MAX_ENTRIES];
 } __attribute__ ((__packed__));
 
+#define BITMAP_MAGIC 0x6d746962
+
+/* use these for bitmap->flags and bitmap->sb->state bit-fields */
+enum bitmap_state {
+	BITMAP_STALE	   = 1,  /* the bitmap file is out of date or had -EIO */
+	BITMAP_WRITE_ERROR = 2, /* A write error has occurred */
+	BITMAP_HOSTENDIAN  =15,
+};
+
+/* the superblock at the front of the bitmap file -- little endian */
+typedef struct bitmap_super_s {
+	__le32 magic;        /*  0  BITMAP_MAGIC */
+	__le32 version;      /*  4  the bitmap major for now, could change... */
+	__u8  uuid[16];      /*  8  128 bit uuid - must match md device uuid */
+	__le64 events;       /* 24  event counter for the bitmap (1)*/
+	__le64 events_cleared;/*32  event counter when last bit cleared (2) */
+	__le64 sync_size;    /* 40  the size of the md device's sync range(3) */
+	__le32 state;        /* 48  bitmap state information */
+	__le32 chunksize;    /* 52  the bitmap chunk size in bytes */
+	__le32 daemon_sleep; /* 56  seconds between disk flushes */
+	__le32 write_behind; /* 60  number of outstanding write-behind writes */
+	__le32 sectors_reserved; /* 64 number of 512-byte sectors that are
+				  * reserved for the bitmap. */
+	__le32 nodes;        /* 68 the maximum number of nodes in cluster. */
+	__u8 cluster_name[64]; /* 72 cluster name to which this md belongs */
+	__u8  pad[256 - 136]; /* set to zero */
+} bitmap_super_t;
+
+/* notes:
+ * (1) This event counter is updated before the eventcounter in the md superblock
+ *    When a bitmap is loaded, it is only accepted if this event counter is equal
+ *    to, or one greater than, the event counter in the superblock.
+ * (2) This event counter is updated when the other one is *if*and*only*if* the
+ *    array is not degraded.  As bits are not cleared when the array is degraded,
+ *    this represents the last time that any bits were cleared.
+ *    If a device is being added that has an event count with this value or
+ *    higher, it is accepted as conforming to the bitmap.
+ * (3)This is the number of sectors represented by the bitmap, and is the range that
+ *    resync happens across.  For raid1 and raid5/6 it is the size of individual
+ *    devices.  For raid10 it is the size of the array.
+ */
+
 #endif
-- 
2.47.1

Re: [PATCH] Export MDRAID bitmap on disk structure in UAPI header file

[Yu Kuai]

Hi,

在 2024/12/31 11:09, Tomas Mudrunka 写道:
> When working on software that manages MD RAID disks from
> userspace. Currently provided headers only contain MD superblock.
> That is not enough to fully populate MD RAID metadata.
> Therefore this patch adds bitmap superblock as well.
> 

Thanks for the patch, however, Why do you want to directly manipulate
the metadata instead of using mdadm? You must first provide an
explanation to convince us that what you're doing makes sense, and
it's best to show your work.

Thanks,
Kuai

> Signed-off-by: Tomas Mudrunka <tomas.mudrunka@gmail.com>
> ---
>   drivers/md/md-bitmap.h         | 42 +-------------------------------
>   include/uapi/linux/raid/md_p.h | 44 +++++++++++++++++++++++++++++++++-
>   2 files changed, 44 insertions(+), 42 deletions(-)
> 
> diff --git a/drivers/md/md-bitmap.h b/drivers/md/md-bitmap.h
> index 662e6fc14..6050d422b 100644
> --- a/drivers/md/md-bitmap.h
> +++ b/drivers/md/md-bitmap.h
> @@ -7,7 +7,7 @@
>   #ifndef BITMAP_H
>   #define BITMAP_H 1
>   
> -#define BITMAP_MAGIC 0x6d746962
> +#include <linux/raid/md_p.h>
>   
>   typedef __u16 bitmap_counter_t;
>   #define COUNTER_BITS 16
> @@ -18,46 +18,6 @@ typedef __u16 bitmap_counter_t;
>   #define RESYNC_MASK ((bitmap_counter_t) (1 << (COUNTER_BITS - 2)))
>   #define COUNTER_MAX ((bitmap_counter_t) RESYNC_MASK - 1)
>   
> -/* use these for bitmap->flags and bitmap->sb->state bit-fields */
> -enum bitmap_state {
> -	BITMAP_STALE	   = 1,  /* the bitmap file is out of date or had -EIO */
> -	BITMAP_WRITE_ERROR = 2, /* A write error has occurred */
> -	BITMAP_HOSTENDIAN  =15,
> -};
> -
> -/* the superblock at the front of the bitmap file -- little endian */
> -typedef struct bitmap_super_s {
> -	__le32 magic;        /*  0  BITMAP_MAGIC */
> -	__le32 version;      /*  4  the bitmap major for now, could change... */
> -	__u8  uuid[16];      /*  8  128 bit uuid - must match md device uuid */
> -	__le64 events;       /* 24  event counter for the bitmap (1)*/
> -	__le64 events_cleared;/*32  event counter when last bit cleared (2) */
> -	__le64 sync_size;    /* 40  the size of the md device's sync range(3) */
> -	__le32 state;        /* 48  bitmap state information */
> -	__le32 chunksize;    /* 52  the bitmap chunk size in bytes */
> -	__le32 daemon_sleep; /* 56  seconds between disk flushes */
> -	__le32 write_behind; /* 60  number of outstanding write-behind writes */
> -	__le32 sectors_reserved; /* 64 number of 512-byte sectors that are
> -				  * reserved for the bitmap. */
> -	__le32 nodes;        /* 68 the maximum number of nodes in cluster. */
> -	__u8 cluster_name[64]; /* 72 cluster name to which this md belongs */
> -	__u8  pad[256 - 136]; /* set to zero */
> -} bitmap_super_t;
> -
> -/* notes:
> - * (1) This event counter is updated before the eventcounter in the md superblock
> - *    When a bitmap is loaded, it is only accepted if this event counter is equal
> - *    to, or one greater than, the event counter in the superblock.
> - * (2) This event counter is updated when the other one is *if*and*only*if* the
> - *    array is not degraded.  As bits are not cleared when the array is degraded,
> - *    this represents the last time that any bits were cleared.
> - *    If a device is being added that has an event count with this value or
> - *    higher, it is accepted as conforming to the bitmap.
> - * (3)This is the number of sectors represented by the bitmap, and is the range that
> - *    resync happens across.  For raid1 and raid5/6 it is the size of individual
> - *    devices.  For raid10 it is the size of the array.
> - */
> -
>   struct md_bitmap_stats {
>   	u64		events_cleared;
>   	int		behind_writes;
> diff --git a/include/uapi/linux/raid/md_p.h b/include/uapi/linux/raid/md_p.h
> index 5a43c23f5..8131e7713 100644
> --- a/include/uapi/linux/raid/md_p.h
> +++ b/include/uapi/linux/raid/md_p.h
> @@ -1,7 +1,7 @@
>   /* SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note */
>   /*
>      md_p.h : physical layout of Linux RAID devices
> -          Copyright (C) 1996-98 Ingo Molnar, Gadi Oxman
> +          Copyright (C) 1996-98 Ingo Molnar, Gadi Oxman, Peter T. Breuer
>   
>      This program is free software; you can redistribute it and/or modify
>      it under the terms of the GNU General Public License as published by
> @@ -426,4 +426,46 @@ struct ppl_header {
>   	struct ppl_header_entry entries[PPL_HDR_MAX_ENTRIES];
>   } __attribute__ ((__packed__));
>   
> +#define BITMAP_MAGIC 0x6d746962
> +
> +/* use these for bitmap->flags and bitmap->sb->state bit-fields */
> +enum bitmap_state {
> +	BITMAP_STALE	   = 1,  /* the bitmap file is out of date or had -EIO */
> +	BITMAP_WRITE_ERROR = 2, /* A write error has occurred */
> +	BITMAP_HOSTENDIAN  =15,
> +};
> +
> +/* the superblock at the front of the bitmap file -- little endian */
> +typedef struct bitmap_super_s {
> +	__le32 magic;        /*  0  BITMAP_MAGIC */
> +	__le32 version;      /*  4  the bitmap major for now, could change... */
> +	__u8  uuid[16];      /*  8  128 bit uuid - must match md device uuid */
> +	__le64 events;       /* 24  event counter for the bitmap (1)*/
> +	__le64 events_cleared;/*32  event counter when last bit cleared (2) */
> +	__le64 sync_size;    /* 40  the size of the md device's sync range(3) */
> +	__le32 state;        /* 48  bitmap state information */
> +	__le32 chunksize;    /* 52  the bitmap chunk size in bytes */
> +	__le32 daemon_sleep; /* 56  seconds between disk flushes */
> +	__le32 write_behind; /* 60  number of outstanding write-behind writes */
> +	__le32 sectors_reserved; /* 64 number of 512-byte sectors that are
> +				  * reserved for the bitmap. */
> +	__le32 nodes;        /* 68 the maximum number of nodes in cluster. */
> +	__u8 cluster_name[64]; /* 72 cluster name to which this md belongs */
> +	__u8  pad[256 - 136]; /* set to zero */
> +} bitmap_super_t;
> +
> +/* notes:
> + * (1) This event counter is updated before the eventcounter in the md superblock
> + *    When a bitmap is loaded, it is only accepted if this event counter is equal
> + *    to, or one greater than, the event counter in the superblock.
> + * (2) This event counter is updated when the other one is *if*and*only*if* the
> + *    array is not degraded.  As bits are not cleared when the array is degraded,
> + *    this represents the last time that any bits were cleared.
> + *    If a device is being added that has an event count with this value or
> + *    higher, it is accepted as conforming to the bitmap.
> + * (3)This is the number of sectors represented by the bitmap, and is the range that
> + *    resync happens across.  For raid1 and raid5/6 it is the size of individual
> + *    devices.  For raid10 it is the size of the array.
> + */
> +
>   #endif
> 

Re: [PATCH] Export MDRAID bitmap on disk structure in UAPI header file

[Mariusz Tkaczyk]

On Tue, 31 Dec 2024 11:47:23 +0800
Yu Kuai <yukuai1@huaweicloud.com> wrote:

> Hi,
> 
> 在 2024/12/31 11:09, Tomas Mudrunka 写道:
> > When working on software that manages MD RAID disks from
> > userspace. Currently provided headers only contain MD superblock.
> > That is not enough to fully populate MD RAID metadata.
> > Therefore this patch adds bitmap superblock as well.
> >   
> 
> Thanks for the patch, however, Why do you want to directly manipulate
> the metadata instead of using mdadm? You must first provide an
> explanation to convince us that what you're doing makes sense, and
> it's best to show your work.
> 
> Thanks,
> Kuai

I'm with Kuai here. I would also add that for such purposes you can use
externally managed metadata, not native. External management was
proposed to address your problem however over the years it turned out
to not be good conception (kernel driver relies on userspace daemon
which is not secure).

Thanks,
Mariusz

Re: [PATCH] Export MDRAID bitmap on disk structure in UAPI header file

[Tomáš Mudruňka]

> > Thanks for the patch, however, Why do you want to directly manipulate
> > the metadata instead of using mdadm? You must first provide an
> > explanation to convince us that what you're doing makes sense, and
> > it's best to show your work.

I am adding MD RAID support to genimage tool:
https://github.com/pengutronix/genimage/

It is used to generate firmware/disk images. Without such a tool it is
impossible to build disk image containing md raid metadata without
actually assembling it in the kernel via losetup or something...

I am already using #include <linux/raid/md_p.h> which includes
references to bitmap structures:

$ grep -ri bitmap /usr/include/linux/raid/md_p.h
#define    MD_SB_BITMAP_PRESENT    8 /* bitmap may be present nearby */
    __le32    feature_map;    /* bit 0 set if 'bitmap_offset' is meaningful */
        __le32    bitmap_offset;    /* sectors after start of
superblock that bitmap starts
                     * NOTE: signed, so bitmap can be before superblock
#define MD_FEATURE_BITMAP_OFFSET    1
#define    MD_FEATURE_RECOVERY_BITMAP    128 /* recovery that is happening
                         * is guided by bitmap.
#define    MD_FEATURE_ALL            (MD_FEATURE_BITMAP_OFFSET    \
                    |MD_FEATURE_RECOVERY_BITMAP    \

But when i use those, the resulting metadata is invalid, unless i populate
the structures from drivers/md/md-bitmap.h so i had to copypaste its contents
to my code, but i am not happy about it (including half and copypasting half):

https://github.com/Harvie/genimage/blob/master/image-mdraid.c

> I'm with Kuai here. I would also add that for such purposes you can use
> externally managed metadata, not native. External management was
> proposed to address your problem however over the years it turned out
> to not be good conception (kernel driver relies on userspace daemon
> which is not secure).
>
> Thanks,
> Mariusz

Hope my reply is sufficient.

Thank you guys!
Tom

Re: [PATCH] Export MDRAID bitmap on disk structure in UAPI header file

[Christoph Hellwig]

On Tue, Dec 31, 2024 at 04:09:27AM +0100, Tomas Mudrunka wrote:
> When working on software that manages MD RAID disks from
> userspace. Currently provided headers only contain MD superblock.
> That is not enough to fully populate MD RAID metadata.
> Therefore this patch adds bitmap superblock as well.

the bitmap format is not a userspace ABI, it is an on-disk format.
As such it does not belong into the uapi.  It might make sense to
create a clean standalone header just for the on-disk format that
you could copy, though.

Re: [PATCH] Export MDRAID bitmap on disk structure in UAPI header file

[Tomáš Mudruňka]

> the bitmap format is not a userspace ABI, it is an on-disk format.
> As such it does not belong into the uapi.  It might make sense to
> create a clean standalone header just for the on-disk format that
> you could copy, though.

If you inspect the header in question, you'll find that this is the exact
reason why this header exists. To describe "physical layout" of
MD RAID devices. Which is just fancy way to say "on disk format".


$ head /usr/include/linux/raid/md_p.h
/* SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note */
/*
   md_p.h : physical layout of Linux RAID devices
          Copyright (C) 1996-98 Ingo Molnar, Gadi Oxman

po 6. 1. 2025 v 16:25 odesílatel Christoph Hellwig <hch@infradead.org> napsal:
>
> On Tue, Dec 31, 2024 at 04:09:27AM +0100, Tomas Mudrunka wrote:
> > When working on software that manages MD RAID disks from
> > userspace. Currently provided headers only contain MD superblock.
> > That is not enough to fully populate MD RAID metadata.
> > Therefore this patch adds bitmap superblock as well.
>
> the bitmap format is not a userspace ABI, it is an on-disk format.
> As such it does not belong into the uapi.  It might make sense to
> create a clean standalone header just for the on-disk format that
> you could copy, though.
>

Re: [PATCH] Export MDRAID bitmap on disk structure in UAPI header file

[Christoph Hellwig]

On Mon, Jan 06, 2025 at 04:40:52PM +0100, Tomáš Mudruňka wrote:
> > the bitmap format is not a userspace ABI, it is an on-disk format.
> > As such it does not belong into the uapi.  It might make sense to
> > create a clean standalone header just for the on-disk format that
> > you could copy, though.
> 
> If you inspect the header in question, you'll find that this is the exact
> reason why this header exists. To describe "physical layout" of
> MD RAID devices. Which is just fancy way to say "on disk format".

Well, then MD already gets it wrong.  No reason to do more of the same.

Re: [PATCH] Export MDRAID bitmap on disk structure in UAPI header file

[Mariusz Tkaczyk]

On Tue, 31 Dec 2024 04:09:27 +0100
Tomas Mudrunka <tomas.mudrunka@gmail.com> wrote:

> When working on software that manages MD RAID disks from
> userspace. Currently provided headers only contain MD superblock.
> That is not enough to fully populate MD RAID metadata.
> Therefore this patch adds bitmap superblock as well.
> 
> Signed-off-by: Tomas Mudrunka <tomas.mudrunka@gmail.com>
> ---

Hello Tomas,
Jumping here again.. I tried to build mdadm against your patch.
In mdadm we used copied headers for years. I submitted PR for review:
This simple one to remove legacy ifdef:
https://github.com/md-raid-utilities/mdadm/pull/148

And this one to start using kernel provided headers:
https://github.com/md-raid-utilities/mdadm/pull/149

Going back to you change, to integrate it with mdadm well I need:
/* Notify that kernel provides it */
#define MD_BITMAP_SUBERBLOCK_EXPORTED 1 

Probably I can use any define to check it, but for clarity I would like
to keep clear differentiation. I hope it is not a problem.

And missing defines used by mdadm:

#define BITMAP_MAJOR_LO 3
/* version 4 insists the bitmap is in little-endian order
 * with version 3, it is host-endian which is non-portable
 */
#define BITMAP_MAJOR_HI 4
#define	BITMAP_MAJOR_CLUSTERED 5

see:
https://github.com/md-raid-utilities/mdadm/blob/main/bitmap.h


After that, I should be able to compile mdadm.

Thanks,
Mariusz

[PATCH v2] Export MDRAID bitmap on disk structure in UAPI header file

[Tomas Mudrunka]

When working on software that manages MD RAID disks from
userspace. Currently provided headers only contain MD superblock.
That is not enough to fully populate MD RAID metadata.
Therefore this patch adds bitmap superblock as well.

Signed-off-by: Tomas Mudrunka <tomas.mudrunka@gmail.com>
---
V1 -> V2: Also exported stuff needed by mdadm according to Mariusz Tkaczyk

 drivers/md/md-bitmap.c         |  9 ------
 drivers/md/md-bitmap.h         | 42 +--------------------------
 include/uapi/linux/raid/md_p.h | 52 +++++++++++++++++++++++++++++++++-
 3 files changed, 52 insertions(+), 51 deletions(-)

diff --git a/drivers/md/md-bitmap.c b/drivers/md/md-bitmap.c
index ec4ecd96e..247610f9a 100644
--- a/drivers/md/md-bitmap.c
+++ b/drivers/md/md-bitmap.c
@@ -32,15 +32,6 @@
 #include "md.h"
 #include "md-bitmap.h"
 
-#define BITMAP_MAJOR_LO 3
-/* version 4 insists the bitmap is in little-endian order
- * with version 3, it is host-endian which is non-portable
- * Version 5 is currently set only for clustered devices
- */
-#define BITMAP_MAJOR_HI 4
-#define BITMAP_MAJOR_CLUSTERED 5
-#define	BITMAP_MAJOR_HOSTENDIAN 3
-
 /*
  * in-memory bitmap:
  *
diff --git a/drivers/md/md-bitmap.h b/drivers/md/md-bitmap.h
index 31c93019c..75bbe6b84 100644
--- a/drivers/md/md-bitmap.h
+++ b/drivers/md/md-bitmap.h
@@ -7,7 +7,7 @@
 #ifndef BITMAP_H
 #define BITMAP_H 1
 
-#define BITMAP_MAGIC 0x6d746962
+#include <linux/raid/md_p.h>
 
 typedef __u16 bitmap_counter_t;
 #define COUNTER_BITS 16
@@ -18,46 +18,6 @@ typedef __u16 bitmap_counter_t;
 #define RESYNC_MASK ((bitmap_counter_t) (1 << (COUNTER_BITS - 2)))
 #define COUNTER_MAX ((bitmap_counter_t) RESYNC_MASK - 1)
 
-/* use these for bitmap->flags and bitmap->sb->state bit-fields */
-enum bitmap_state {
-	BITMAP_STALE	   = 1,  /* the bitmap file is out of date or had -EIO */
-	BITMAP_WRITE_ERROR = 2, /* A write error has occurred */
-	BITMAP_HOSTENDIAN  =15,
-};
-
-/* the superblock at the front of the bitmap file -- little endian */
-typedef struct bitmap_super_s {
-	__le32 magic;        /*  0  BITMAP_MAGIC */
-	__le32 version;      /*  4  the bitmap major for now, could change... */
-	__u8  uuid[16];      /*  8  128 bit uuid - must match md device uuid */
-	__le64 events;       /* 24  event counter for the bitmap (1)*/
-	__le64 events_cleared;/*32  event counter when last bit cleared (2) */
-	__le64 sync_size;    /* 40  the size of the md device's sync range(3) */
-	__le32 state;        /* 48  bitmap state information */
-	__le32 chunksize;    /* 52  the bitmap chunk size in bytes */
-	__le32 daemon_sleep; /* 56  seconds between disk flushes */
-	__le32 write_behind; /* 60  number of outstanding write-behind writes */
-	__le32 sectors_reserved; /* 64 number of 512-byte sectors that are
-				  * reserved for the bitmap. */
-	__le32 nodes;        /* 68 the maximum number of nodes in cluster. */
-	__u8 cluster_name[64]; /* 72 cluster name to which this md belongs */
-	__u8  pad[256 - 136]; /* set to zero */
-} bitmap_super_t;
-
-/* notes:
- * (1) This event counter is updated before the eventcounter in the md superblock
- *    When a bitmap is loaded, it is only accepted if this event counter is equal
- *    to, or one greater than, the event counter in the superblock.
- * (2) This event counter is updated when the other one is *if*and*only*if* the
- *    array is not degraded.  As bits are not cleared when the array is degraded,
- *    this represents the last time that any bits were cleared.
- *    If a device is being added that has an event count with this value or
- *    higher, it is accepted as conforming to the bitmap.
- * (3)This is the number of sectors represented by the bitmap, and is the range that
- *    resync happens across.  For raid1 and raid5/6 it is the size of individual
- *    devices.  For raid10 it is the size of the array.
- */
-
 struct md_bitmap_stats {
 	u64		events_cleared;
 	int		behind_writes;
diff --git a/include/uapi/linux/raid/md_p.h b/include/uapi/linux/raid/md_p.h
index ff47b6f0b..3684c0001 100644
--- a/include/uapi/linux/raid/md_p.h
+++ b/include/uapi/linux/raid/md_p.h
@@ -1,7 +1,7 @@
 /* SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note */
 /*
    md_p.h : physical layout of Linux RAID devices
-          Copyright (C) 1996-98 Ingo Molnar, Gadi Oxman
+          Copyright (C) 1996-98 Ingo Molnar, Gadi Oxman, Peter T. Breuer
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -426,4 +426,54 @@ struct ppl_header {
 	struct ppl_header_entry entries[PPL_HDR_MAX_ENTRIES];
 } __attribute__ ((__packed__));
 
+#define MD_BITMAP_SUBERBLOCK_EXPORTED 1	/* Notify that kernel provides it */
+#define BITMAP_MAGIC 0x6d746962		/* This is actualy "bitm" in ASCII :-) */
+#define BITMAP_MAJOR_LO 3
+/* version 4 insists the bitmap is in little-endian order
+ * with version 3, it is host-endian which is non-portable
+ */
+#define BITMAP_MAJOR_HI 4
+#define BITMAP_MAJOR_CLUSTERED 5
+#define BITMAP_MAJOR_HOSTENDIAN 3
+
+/* use these for bitmap->flags and bitmap->sb->state bit-fields */
+enum bitmap_state {
+	BITMAP_STALE	   = 1,  /* the bitmap file is out of date or had -EIO */
+	BITMAP_WRITE_ERROR = 2, /* A write error has occurred */
+	BITMAP_HOSTENDIAN  =15,
+};
+
+/* the superblock at the front of the bitmap file -- little endian */
+typedef struct bitmap_super_s {
+	__le32 magic;        /*  0  BITMAP_MAGIC */
+	__le32 version;      /*  4  the bitmap major for now, could change... */
+	__u8  uuid[16];      /*  8  128 bit uuid - must match md device uuid */
+	__le64 events;       /* 24  event counter for the bitmap (1)*/
+	__le64 events_cleared;/*32  event counter when last bit cleared (2) */
+	__le64 sync_size;    /* 40  the size of the md device's sync range(3) */
+	__le32 state;        /* 48  bitmap state information */
+	__le32 chunksize;    /* 52  the bitmap chunk size in bytes */
+	__le32 daemon_sleep; /* 56  seconds between disk flushes */
+	__le32 write_behind; /* 60  number of outstanding write-behind writes */
+	__le32 sectors_reserved; /* 64 number of 512-byte sectors that are
+				  * reserved for the bitmap. */
+	__le32 nodes;        /* 68 the maximum number of nodes in cluster. */
+	__u8 cluster_name[64]; /* 72 cluster name to which this md belongs */
+	__u8  pad[256 - 136]; /* set to zero */
+} bitmap_super_t;
+
+/* notes:
+ * (1) This event counter is updated before the eventcounter in the md superblock
+ *    When a bitmap is loaded, it is only accepted if this event counter is equal
+ *    to, or one greater than, the event counter in the superblock.
+ * (2) This event counter is updated when the other one is *if*and*only*if* the
+ *    array is not degraded.  As bits are not cleared when the array is degraded,
+ *    this represents the last time that any bits were cleared.
+ *    If a device is being added that has an event count with this value or
+ *    higher, it is accepted as conforming to the bitmap.
+ * (3)This is the number of sectors represented by the bitmap, and is the range that
+ *    resync happens across.  For raid1 and raid5/6 it is the size of individual
+ *    devices.  For raid10 it is the size of the array.
+ */
+
 #endif
-- 
2.48.1

[PATCH v3] Export MDRAID bitmap on disk structure in UAPI header file

[Tomas Mudrunka]

When working on software that manages MD RAID disks from
userspace. Currently provided headers only contain MD superblock.
That is not enough to fully populate MD RAID metadata.
Therefore this patch adds bitmap superblock as well.

Signed-off-by: Tomas Mudrunka <tomas.mudrunka@gmail.com>
---
V1 -> V2: Also exported stuff needed by mdadm according to Mariusz Tkaczyk
V2 -> V3: Fixed checkpatch errors

 drivers/md/md-bitmap.c         |  9 ------
 drivers/md/md-bitmap.h         | 42 +--------------------------
 include/uapi/linux/raid/md_p.h | 53 +++++++++++++++++++++++++++++++++-
 3 files changed, 53 insertions(+), 51 deletions(-)

diff --git a/drivers/md/md-bitmap.c b/drivers/md/md-bitmap.c
index ec4ecd96e..247610f9a 100644
--- a/drivers/md/md-bitmap.c
+++ b/drivers/md/md-bitmap.c
@@ -32,15 +32,6 @@
 #include "md.h"
 #include "md-bitmap.h"
 
-#define BITMAP_MAJOR_LO 3
-/* version 4 insists the bitmap is in little-endian order
- * with version 3, it is host-endian which is non-portable
- * Version 5 is currently set only for clustered devices
- */
-#define BITMAP_MAJOR_HI 4
-#define BITMAP_MAJOR_CLUSTERED 5
-#define	BITMAP_MAJOR_HOSTENDIAN 3
-
 /*
  * in-memory bitmap:
  *
diff --git a/drivers/md/md-bitmap.h b/drivers/md/md-bitmap.h
index 31c93019c..75bbe6b84 100644
--- a/drivers/md/md-bitmap.h
+++ b/drivers/md/md-bitmap.h
@@ -7,7 +7,7 @@
 #ifndef BITMAP_H
 #define BITMAP_H 1
 
-#define BITMAP_MAGIC 0x6d746962
+#include <linux/raid/md_p.h>
 
 typedef __u16 bitmap_counter_t;
 #define COUNTER_BITS 16
@@ -18,46 +18,6 @@ typedef __u16 bitmap_counter_t;
 #define RESYNC_MASK ((bitmap_counter_t) (1 << (COUNTER_BITS - 2)))
 #define COUNTER_MAX ((bitmap_counter_t) RESYNC_MASK - 1)
 
-/* use these for bitmap->flags and bitmap->sb->state bit-fields */
-enum bitmap_state {
-	BITMAP_STALE	   = 1,  /* the bitmap file is out of date or had -EIO */
-	BITMAP_WRITE_ERROR = 2, /* A write error has occurred */
-	BITMAP_HOSTENDIAN  =15,
-};
-
-/* the superblock at the front of the bitmap file -- little endian */
-typedef struct bitmap_super_s {
-	__le32 magic;        /*  0  BITMAP_MAGIC */
-	__le32 version;      /*  4  the bitmap major for now, could change... */
-	__u8  uuid[16];      /*  8  128 bit uuid - must match md device uuid */
-	__le64 events;       /* 24  event counter for the bitmap (1)*/
-	__le64 events_cleared;/*32  event counter when last bit cleared (2) */
-	__le64 sync_size;    /* 40  the size of the md device's sync range(3) */
-	__le32 state;        /* 48  bitmap state information */
-	__le32 chunksize;    /* 52  the bitmap chunk size in bytes */
-	__le32 daemon_sleep; /* 56  seconds between disk flushes */
-	__le32 write_behind; /* 60  number of outstanding write-behind writes */
-	__le32 sectors_reserved; /* 64 number of 512-byte sectors that are
-				  * reserved for the bitmap. */
-	__le32 nodes;        /* 68 the maximum number of nodes in cluster. */
-	__u8 cluster_name[64]; /* 72 cluster name to which this md belongs */
-	__u8  pad[256 - 136]; /* set to zero */
-} bitmap_super_t;
-
-/* notes:
- * (1) This event counter is updated before the eventcounter in the md superblock
- *    When a bitmap is loaded, it is only accepted if this event counter is equal
- *    to, or one greater than, the event counter in the superblock.
- * (2) This event counter is updated when the other one is *if*and*only*if* the
- *    array is not degraded.  As bits are not cleared when the array is degraded,
- *    this represents the last time that any bits were cleared.
- *    If a device is being added that has an event count with this value or
- *    higher, it is accepted as conforming to the bitmap.
- * (3)This is the number of sectors represented by the bitmap, and is the range that
- *    resync happens across.  For raid1 and raid5/6 it is the size of individual
- *    devices.  For raid10 it is the size of the array.
- */
-
 struct md_bitmap_stats {
 	u64		events_cleared;
 	int		behind_writes;
diff --git a/include/uapi/linux/raid/md_p.h b/include/uapi/linux/raid/md_p.h
index ff47b6f0b..2995528f9 100644
--- a/include/uapi/linux/raid/md_p.h
+++ b/include/uapi/linux/raid/md_p.h
@@ -1,7 +1,7 @@
 /* SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note */
 /*
    md_p.h : physical layout of Linux RAID devices
-          Copyright (C) 1996-98 Ingo Molnar, Gadi Oxman
+	Copyright (C) 1996-98 Ingo Molnar, Gadi Oxman, Peter T. Breuer
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -426,4 +426,55 @@ struct ppl_header {
 	struct ppl_header_entry entries[PPL_HDR_MAX_ENTRIES];
 } __attribute__ ((__packed__));
 
+#define MD_BITMAP_SUBERBLOCK_EXPORTED 1	/* Notify that kernel provides it */
+#define BITMAP_MAGIC 0x6d746962		/* This is actually "bitm" in ASCII :-) */
+#define BITMAP_MAJOR_LO 3
+/* version 4 insists the bitmap is in little-endian order
+ * with version 3, it is host-endian which is non-portable
+ */
+#define BITMAP_MAJOR_HI 4
+#define BITMAP_MAJOR_CLUSTERED 5
+#define BITMAP_MAJOR_HOSTENDIAN 3
+
+/* use these for bitmap->flags and bitmap->sb->state bit-fields */
+enum bitmap_state {
+	BITMAP_STALE	   = 1,  /* the bitmap file is out of date or had -EIO */
+	BITMAP_WRITE_ERROR = 2, /* A write error has occurred */
+	BITMAP_HOSTENDIAN  = 15,
+};
+
+/* the superblock at the front of the bitmap file -- little endian */
+typedef struct bitmap_super_s {
+	__le32 magic;        /*  0  BITMAP_MAGIC */
+	__le32 version;      /*  4  the bitmap major for now, could change... */
+	__u8  uuid[16];      /*  8  128 bit uuid - must match md device uuid */
+	__le64 events;       /* 24  event counter for the bitmap (1)*/
+	__le64 events_cleared;/*32  event counter when last bit cleared (2) */
+	__le64 sync_size;    /* 40  the size of the md device's sync range(3) */
+	__le32 state;        /* 48  bitmap state information */
+	__le32 chunksize;    /* 52  the bitmap chunk size in bytes */
+	__le32 daemon_sleep; /* 56  seconds between disk flushes */
+	__le32 write_behind; /* 60  number of outstanding write-behind writes */
+	__le32 sectors_reserved; /* 64 number of 512-byte sectors that are
+				  * reserved for the bitmap.
+				  */
+	__le32 nodes;        /* 68 the maximum number of nodes in cluster. */
+	__u8 cluster_name[64]; /* 72 cluster name to which this md belongs */
+	__u8  pad[256 - 136]; /* set to zero */
+} bitmap_super_t;
+
+/* notes:
+ * (1) This event counter is updated before the eventcounter in the md superblock
+ *    When a bitmap is loaded, it is only accepted if this event counter is equal
+ *    to, or one greater than, the event counter in the superblock.
+ * (2) This event counter is updated when the other one is *if*and*only*if* the
+ *    array is not degraded.  As bits are not cleared when the array is degraded,
+ *    this represents the last time that any bits were cleared.
+ *    If a device is being added that has an event count with this value or
+ *    higher, it is accepted as conforming to the bitmap.
+ * (3)This is the number of sectors represented by the bitmap, and is the range that
+ *    resync happens across.  For raid1 and raid5/6 it is the size of individual
+ *    devices.  For raid10 it is the size of the array.
+ */
+
 #endif
-- 
2.48.1

Re: [PATCH v3] Export MDRAID bitmap on disk structure in UAPI header file

[Yu Kuai]

Hi, Tomas

在 2025/02/07 6:30, Tomas Mudrunka 写道:
> When working on software that manages MD RAID disks from
> userspace. Currently provided headers only contain MD superblock.
> That is not enough to fully populate MD RAID metadata.
> Therefore this patch adds bitmap superblock as well.
> 
> Signed-off-by: Tomas Mudrunka <tomas.mudrunka@gmail.com>
> ---

Can you fix the checkpatch warning and send a new version?

Thanks,
Kuai

> V1 -> V2: Also exported stuff needed by mdadm according to Mariusz Tkaczyk
> V2 -> V3: Fixed checkpatch errors
> 
>   drivers/md/md-bitmap.c         |  9 ------
>   drivers/md/md-bitmap.h         | 42 +--------------------------
>   include/uapi/linux/raid/md_p.h | 53 +++++++++++++++++++++++++++++++++-
>   3 files changed, 53 insertions(+), 51 deletions(-)
> 
> diff --git a/drivers/md/md-bitmap.c b/drivers/md/md-bitmap.c
> index ec4ecd96e..247610f9a 100644
> --- a/drivers/md/md-bitmap.c
> +++ b/drivers/md/md-bitmap.c
> @@ -32,15 +32,6 @@
>   #include "md.h"
>   #include "md-bitmap.h"
>   
> -#define BITMAP_MAJOR_LO 3
> -/* version 4 insists the bitmap is in little-endian order
> - * with version 3, it is host-endian which is non-portable
> - * Version 5 is currently set only for clustered devices
> - */
> -#define BITMAP_MAJOR_HI 4
> -#define BITMAP_MAJOR_CLUSTERED 5
> -#define	BITMAP_MAJOR_HOSTENDIAN 3
> -
>   /*
>    * in-memory bitmap:
>    *
> diff --git a/drivers/md/md-bitmap.h b/drivers/md/md-bitmap.h
> index 31c93019c..75bbe6b84 100644
> --- a/drivers/md/md-bitmap.h
> +++ b/drivers/md/md-bitmap.h
> @@ -7,7 +7,7 @@
>   #ifndef BITMAP_H
>   #define BITMAP_H 1
>   
> -#define BITMAP_MAGIC 0x6d746962
> +#include <linux/raid/md_p.h>
>   
>   typedef __u16 bitmap_counter_t;
>   #define COUNTER_BITS 16
> @@ -18,46 +18,6 @@ typedef __u16 bitmap_counter_t;
>   #define RESYNC_MASK ((bitmap_counter_t) (1 << (COUNTER_BITS - 2)))
>   #define COUNTER_MAX ((bitmap_counter_t) RESYNC_MASK - 1)
>   
> -/* use these for bitmap->flags and bitmap->sb->state bit-fields */
> -enum bitmap_state {
> -	BITMAP_STALE	   = 1,  /* the bitmap file is out of date or had -EIO */
> -	BITMAP_WRITE_ERROR = 2, /* A write error has occurred */
> -	BITMAP_HOSTENDIAN  =15,
> -};
> -
> -/* the superblock at the front of the bitmap file -- little endian */
> -typedef struct bitmap_super_s {
> -	__le32 magic;        /*  0  BITMAP_MAGIC */
> -	__le32 version;      /*  4  the bitmap major for now, could change... */
> -	__u8  uuid[16];      /*  8  128 bit uuid - must match md device uuid */
> -	__le64 events;       /* 24  event counter for the bitmap (1)*/
> -	__le64 events_cleared;/*32  event counter when last bit cleared (2) */
> -	__le64 sync_size;    /* 40  the size of the md device's sync range(3) */
> -	__le32 state;        /* 48  bitmap state information */
> -	__le32 chunksize;    /* 52  the bitmap chunk size in bytes */
> -	__le32 daemon_sleep; /* 56  seconds between disk flushes */
> -	__le32 write_behind; /* 60  number of outstanding write-behind writes */
> -	__le32 sectors_reserved; /* 64 number of 512-byte sectors that are
> -				  * reserved for the bitmap. */
> -	__le32 nodes;        /* 68 the maximum number of nodes in cluster. */
> -	__u8 cluster_name[64]; /* 72 cluster name to which this md belongs */
> -	__u8  pad[256 - 136]; /* set to zero */
> -} bitmap_super_t;
> -
> -/* notes:
> - * (1) This event counter is updated before the eventcounter in the md superblock
> - *    When a bitmap is loaded, it is only accepted if this event counter is equal
> - *    to, or one greater than, the event counter in the superblock.
> - * (2) This event counter is updated when the other one is *if*and*only*if* the
> - *    array is not degraded.  As bits are not cleared when the array is degraded,
> - *    this represents the last time that any bits were cleared.
> - *    If a device is being added that has an event count with this value or
> - *    higher, it is accepted as conforming to the bitmap.
> - * (3)This is the number of sectors represented by the bitmap, and is the range that
> - *    resync happens across.  For raid1 and raid5/6 it is the size of individual
> - *    devices.  For raid10 it is the size of the array.
> - */
> -
>   struct md_bitmap_stats {
>   	u64		events_cleared;
>   	int		behind_writes;
> diff --git a/include/uapi/linux/raid/md_p.h b/include/uapi/linux/raid/md_p.h
> index ff47b6f0b..2995528f9 100644
> --- a/include/uapi/linux/raid/md_p.h
> +++ b/include/uapi/linux/raid/md_p.h
> @@ -1,7 +1,7 @@
>   /* SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note */
>   /*
>      md_p.h : physical layout of Linux RAID devices
> -          Copyright (C) 1996-98 Ingo Molnar, Gadi Oxman
> +	Copyright (C) 1996-98 Ingo Molnar, Gadi Oxman, Peter T. Breuer
>   
>      This program is free software; you can redistribute it and/or modify
>      it under the terms of the GNU General Public License as published by
> @@ -426,4 +426,55 @@ struct ppl_header {
>   	struct ppl_header_entry entries[PPL_HDR_MAX_ENTRIES];
>   } __attribute__ ((__packed__));
>   
> +#define MD_BITMAP_SUBERBLOCK_EXPORTED 1	/* Notify that kernel provides it */
> +#define BITMAP_MAGIC 0x6d746962		/* This is actually "bitm" in ASCII :-) */
> +#define BITMAP_MAJOR_LO 3
> +/* version 4 insists the bitmap is in little-endian order
> + * with version 3, it is host-endian which is non-portable
> + */
> +#define BITMAP_MAJOR_HI 4
> +#define BITMAP_MAJOR_CLUSTERED 5
> +#define BITMAP_MAJOR_HOSTENDIAN 3
> +
> +/* use these for bitmap->flags and bitmap->sb->state bit-fields */
> +enum bitmap_state {
> +	BITMAP_STALE	   = 1,  /* the bitmap file is out of date or had -EIO */
> +	BITMAP_WRITE_ERROR = 2, /* A write error has occurred */
> +	BITMAP_HOSTENDIAN  = 15,
> +};
> +
> +/* the superblock at the front of the bitmap file -- little endian */
> +typedef struct bitmap_super_s {
> +	__le32 magic;        /*  0  BITMAP_MAGIC */
> +	__le32 version;      /*  4  the bitmap major for now, could change... */
> +	__u8  uuid[16];      /*  8  128 bit uuid - must match md device uuid */
> +	__le64 events;       /* 24  event counter for the bitmap (1)*/
> +	__le64 events_cleared;/*32  event counter when last bit cleared (2) */
> +	__le64 sync_size;    /* 40  the size of the md device's sync range(3) */
> +	__le32 state;        /* 48  bitmap state information */
> +	__le32 chunksize;    /* 52  the bitmap chunk size in bytes */
> +	__le32 daemon_sleep; /* 56  seconds between disk flushes */
> +	__le32 write_behind; /* 60  number of outstanding write-behind writes */
> +	__le32 sectors_reserved; /* 64 number of 512-byte sectors that are
> +				  * reserved for the bitmap.
> +				  */
> +	__le32 nodes;        /* 68 the maximum number of nodes in cluster. */
> +	__u8 cluster_name[64]; /* 72 cluster name to which this md belongs */
> +	__u8  pad[256 - 136]; /* set to zero */
> +} bitmap_super_t;
> +
> +/* notes:
> + * (1) This event counter is updated before the eventcounter in the md superblock
> + *    When a bitmap is loaded, it is only accepted if this event counter is equal
> + *    to, or one greater than, the event counter in the superblock.
> + * (2) This event counter is updated when the other one is *if*and*only*if* the
> + *    array is not degraded.  As bits are not cleared when the array is degraded,
> + *    this represents the last time that any bits were cleared.
> + *    If a device is being added that has an event count with this value or
> + *    higher, it is accepted as conforming to the bitmap.
> + * (3)This is the number of sectors represented by the bitmap, and is the range that
> + *    resync happens across.  For raid1 and raid5/6 it is the size of individual
> + *    devices.  For raid10 it is the size of the array.
> + */
> +
>   #endif
> 

[PATCH v4] Export MDRAID bitmap on disk structure in UAPI header file

[Tomas Mudrunka]

When working on software that manages MD RAID disks from
userspace. Currently provided headers only contain MD superblock.
That is not enough to fully populate MD RAID metadata.
Therefore this patch adds bitmap superblock as well.

Signed-off-by: Tomas Mudrunka <tomas.mudrunka@gmail.com>
---
V3 -> V4: Removed typedef
V2 -> V3: Fixed checkpatch errors
V1 -> V2: Also exported stuff needed by mdadm according to Mariusz Tkaczyk

 drivers/md/md-bitmap.c         | 45 +++++++++++---------------
 drivers/md/md-bitmap.h         | 42 +-----------------------
 include/uapi/linux/raid/md_p.h | 58 +++++++++++++++++++++++++++++++++-
 3 files changed, 76 insertions(+), 69 deletions(-)

diff --git a/drivers/md/md-bitmap.c b/drivers/md/md-bitmap.c
index ec4ecd96e..9f7252f08 100644
--- a/drivers/md/md-bitmap.c
+++ b/drivers/md/md-bitmap.c
@@ -32,15 +32,6 @@
 #include "md.h"
 #include "md-bitmap.h"
 
-#define BITMAP_MAJOR_LO 3
-/* version 4 insists the bitmap is in little-endian order
- * with version 3, it is host-endian which is non-portable
- * Version 5 is currently set only for clustered devices
- */
-#define BITMAP_MAJOR_HI 4
-#define BITMAP_MAJOR_CLUSTERED 5
-#define	BITMAP_MAJOR_HOSTENDIAN 3
-
 /*
  * in-memory bitmap:
  *
@@ -673,7 +664,7 @@ static void md_bitmap_wait_writes(struct bitmap *bitmap)
 /* update the event counter and sync the superblock to disk */
 static void bitmap_update_sb(void *data)
 {
-	bitmap_super_t *sb;
+	struct bitmap_super *sb;
 	struct bitmap *bitmap = data;
 
 	if (!bitmap || !bitmap->mddev) /* no bitmap for this array */
@@ -713,7 +704,7 @@ static void bitmap_update_sb(void *data)
 
 static void bitmap_print_sb(struct bitmap *bitmap)
 {
-	bitmap_super_t *sb;
+	struct bitmap_super *sb;
 
 	if (!bitmap || !bitmap->storage.sb_page)
 		return;
@@ -752,7 +743,7 @@ static void bitmap_print_sb(struct bitmap *bitmap)
  */
 static int md_bitmap_new_disk_sb(struct bitmap *bitmap)
 {
-	bitmap_super_t *sb;
+	struct bitmap_super *sb;
 	unsigned long chunksize, daemon_sleep, write_behind;
 
 	bitmap->storage.sb_page = alloc_page(GFP_KERNEL | __GFP_ZERO);
@@ -812,7 +803,7 @@ static int md_bitmap_new_disk_sb(struct bitmap *bitmap)
 static int md_bitmap_read_sb(struct bitmap *bitmap)
 {
 	char *reason = NULL;
-	bitmap_super_t *sb;
+	struct bitmap_super *sb;
 	unsigned long chunksize, daemon_sleep, write_behind;
 	unsigned long long events;
 	int nodes = 0;
@@ -843,7 +834,7 @@ static int md_bitmap_read_sb(struct bitmap *bitmap)
 		bm_blocks = DIV_ROUND_UP_SECTOR_T(bm_blocks,
 			   (bitmap->mddev->bitmap_info.chunksize >> 9));
 		/* bits to bytes */
-		bm_blocks = ((bm_blocks+7) >> 3) + sizeof(bitmap_super_t);
+		bm_blocks = ((bm_blocks+7) >> 3) + sizeof(struct bitmap_super);
 		/* to 4k blocks */
 		bm_blocks = DIV_ROUND_UP_SECTOR_T(bm_blocks, 4096);
 		offset = bitmap->cluster_slot * (bm_blocks << 3);
@@ -859,7 +850,7 @@ static int md_bitmap_read_sb(struct bitmap *bitmap)
 				bitmap, bytes, sb_page);
 	} else {
 		err = read_sb_page(bitmap->mddev, offset, sb_page, 0,
-				   sizeof(bitmap_super_t));
+				   sizeof(struct bitmap_super));
 	}
 	if (err)
 		return err;
@@ -980,7 +971,7 @@ static inline unsigned long file_page_index(struct bitmap_storage *store,
 					    unsigned long chunk)
 {
 	if (store->sb_page)
-		chunk += sizeof(bitmap_super_t) << 3;
+		chunk += sizeof(struct bitmap_super) << 3;
 	return chunk >> PAGE_BIT_SHIFT;
 }
 
@@ -989,7 +980,7 @@ static inline unsigned long file_page_offset(struct bitmap_storage *store,
 					     unsigned long chunk)
 {
 	if (store->sb_page)
-		chunk += sizeof(bitmap_super_t) << 3;
+		chunk += sizeof(struct bitmap_super) << 3;
 	return chunk & (PAGE_BITS - 1);
 }
 
@@ -1015,7 +1006,7 @@ static int md_bitmap_storage_alloc(struct bitmap_storage *store,
 
 	bytes = DIV_ROUND_UP(chunks, 8);
 	if (with_super)
-		bytes += sizeof(bitmap_super_t);
+		bytes += sizeof(struct bitmap_super);
 
 	num_pages = DIV_ROUND_UP(bytes, PAGE_SIZE);
 	offset = slot_number * num_pages;
@@ -1382,7 +1373,7 @@ static int md_bitmap_init_from_disk(struct bitmap *bitmap, sector_t start)
 			void *paddr;
 
 			if (i == 0 && !mddev->bitmap_info.external)
-				offset = sizeof(bitmap_super_t);
+				offset = sizeof(struct bitmap_super);
 
 			/*
 			 * If the bitmap is out of date, dirty the whole page
@@ -1543,7 +1534,7 @@ static void bitmap_daemon_work(struct mddev *mddev)
 	    mddev->bitmap_info.external == 0) {
 		/* Arrange for superblock update as well as
 		 * other changes */
-		bitmap_super_t *sb;
+		struct bitmap_super *sb;
 		bitmap->need_sync = 0;
 		if (bitmap->storage.filemap) {
 			sb = kmap_local_page(bitmap->storage.sb_page);
@@ -2123,7 +2114,7 @@ static struct bitmap *__bitmap_create(struct mddev *mddev, int slot)
 	int err;
 	struct kernfs_node *bm = NULL;
 
-	BUILD_BUG_ON(sizeof(bitmap_super_t) != 256);
+	BUILD_BUG_ON(sizeof(struct bitmap_super) != 256);
 
 	BUG_ON(file && mddev->bitmap_info.offset);
 
@@ -2351,7 +2342,7 @@ static int bitmap_get_stats(void *data, struct md_bitmap_stats *stats)
 	struct bitmap_storage *storage;
 	struct bitmap_counts *counts;
 	struct bitmap *bitmap = data;
-	bitmap_super_t *sb;
+	struct bitmap_super *sb;
 
 	if (!bitmap)
 		return -ENOENT;
@@ -2415,7 +2406,7 @@ static int __bitmap_resize(struct bitmap *bitmap, sector_t blocks,
 			 */
 			bytes = DIV_ROUND_UP(bitmap->counts.chunks, 8);
 			if (!bitmap->mddev->bitmap_info.external)
-				bytes += sizeof(bitmap_super_t);
+				bytes += sizeof(struct bitmap_super);
 			space = DIV_ROUND_UP(bytes, 512);
 			bitmap->mddev->bitmap_info.space = space;
 		}
@@ -2427,9 +2418,9 @@ static int __bitmap_resize(struct bitmap *bitmap, sector_t blocks,
 			chunks = DIV_ROUND_UP_SECTOR_T(blocks, 1 << chunkshift);
 			bytes = DIV_ROUND_UP(chunks, 8);
 			if (!bitmap->mddev->bitmap_info.external)
-				bytes += sizeof(bitmap_super_t);
+				bytes += sizeof(struct bitmap_super);
 		} while (bytes > (space << 9) && (chunkshift + BITMAP_BLOCK_SHIFT) <
-			(BITS_PER_BYTE * sizeof(((bitmap_super_t *)0)->chunksize) - 1));
+			(BITS_PER_BYTE * sizeof(((struct bitmap_super *)0)->chunksize) - 1));
 	} else
 		chunkshift = ffz(~chunksize) - BITMAP_BLOCK_SHIFT;
 
@@ -2463,7 +2454,7 @@ static int __bitmap_resize(struct bitmap *bitmap, sector_t blocks,
 	if (store.sb_page && bitmap->storage.sb_page)
 		memcpy(page_address(store.sb_page),
 		       page_address(bitmap->storage.sb_page),
-		       sizeof(bitmap_super_t));
+		       sizeof(struct bitmap_super));
 	spin_lock_irq(&bitmap->counts.lock);
 	md_bitmap_file_unmap(&bitmap->storage);
 	bitmap->storage = store;
@@ -2859,7 +2850,7 @@ chunksize_store(struct mddev *mddev, const char *buf, size_t len)
 	    !is_power_of_2(csize))
 		return -EINVAL;
 	if (BITS_PER_LONG > 32 && csize >= (1ULL << (BITS_PER_BYTE *
-		sizeof(((bitmap_super_t *)0)->chunksize))))
+		sizeof(((struct bitmap_super *)0)->chunksize))))
 		return -EOVERFLOW;
 	mddev->bitmap_info.chunksize = csize;
 	return len;
diff --git a/drivers/md/md-bitmap.h b/drivers/md/md-bitmap.h
index 31c93019c..75bbe6b84 100644
--- a/drivers/md/md-bitmap.h
+++ b/drivers/md/md-bitmap.h
@@ -7,7 +7,7 @@
 #ifndef BITMAP_H
 #define BITMAP_H 1
 
-#define BITMAP_MAGIC 0x6d746962
+#include <linux/raid/md_p.h>
 
 typedef __u16 bitmap_counter_t;
 #define COUNTER_BITS 16
@@ -18,46 +18,6 @@ typedef __u16 bitmap_counter_t;
 #define RESYNC_MASK ((bitmap_counter_t) (1 << (COUNTER_BITS - 2)))
 #define COUNTER_MAX ((bitmap_counter_t) RESYNC_MASK - 1)
 
-/* use these for bitmap->flags and bitmap->sb->state bit-fields */
-enum bitmap_state {
-	BITMAP_STALE	   = 1,  /* the bitmap file is out of date or had -EIO */
-	BITMAP_WRITE_ERROR = 2, /* A write error has occurred */
-	BITMAP_HOSTENDIAN  =15,
-};
-
-/* the superblock at the front of the bitmap file -- little endian */
-typedef struct bitmap_super_s {
-	__le32 magic;        /*  0  BITMAP_MAGIC */
-	__le32 version;      /*  4  the bitmap major for now, could change... */
-	__u8  uuid[16];      /*  8  128 bit uuid - must match md device uuid */
-	__le64 events;       /* 24  event counter for the bitmap (1)*/
-	__le64 events_cleared;/*32  event counter when last bit cleared (2) */
-	__le64 sync_size;    /* 40  the size of the md device's sync range(3) */
-	__le32 state;        /* 48  bitmap state information */
-	__le32 chunksize;    /* 52  the bitmap chunk size in bytes */
-	__le32 daemon_sleep; /* 56  seconds between disk flushes */
-	__le32 write_behind; /* 60  number of outstanding write-behind writes */
-	__le32 sectors_reserved; /* 64 number of 512-byte sectors that are
-				  * reserved for the bitmap. */
-	__le32 nodes;        /* 68 the maximum number of nodes in cluster. */
-	__u8 cluster_name[64]; /* 72 cluster name to which this md belongs */
-	__u8  pad[256 - 136]; /* set to zero */
-} bitmap_super_t;
-
-/* notes:
- * (1) This event counter is updated before the eventcounter in the md superblock
- *    When a bitmap is loaded, it is only accepted if this event counter is equal
- *    to, or one greater than, the event counter in the superblock.
- * (2) This event counter is updated when the other one is *if*and*only*if* the
- *    array is not degraded.  As bits are not cleared when the array is degraded,
- *    this represents the last time that any bits were cleared.
- *    If a device is being added that has an event count with this value or
- *    higher, it is accepted as conforming to the bitmap.
- * (3)This is the number of sectors represented by the bitmap, and is the range that
- *    resync happens across.  For raid1 and raid5/6 it is the size of individual
- *    devices.  For raid10 it is the size of the array.
- */
-
 struct md_bitmap_stats {
 	u64		events_cleared;
 	int		behind_writes;
diff --git a/include/uapi/linux/raid/md_p.h b/include/uapi/linux/raid/md_p.h
index ff47b6f0b..980a40376 100644
--- a/include/uapi/linux/raid/md_p.h
+++ b/include/uapi/linux/raid/md_p.h
@@ -1,7 +1,7 @@
 /* SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note */
 /*
    md_p.h : physical layout of Linux RAID devices
-          Copyright (C) 1996-98 Ingo Molnar, Gadi Oxman
+	Copyright (C) 1996-98 Ingo Molnar, Gadi Oxman, Peter T. Breuer
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -15,6 +15,11 @@
 #include <linux/types.h>
 #include <asm/byteorder.h>
 
+/*
+ * Note: use of typedefs from this header file is deprecated,
+ * please refer directly to structs when writing new code.
+ */
+
 /*
  * RAID superblock.
  *
@@ -426,4 +431,55 @@ struct ppl_header {
 	struct ppl_header_entry entries[PPL_HDR_MAX_ENTRIES];
 } __attribute__ ((__packed__));
 
+#define MD_BITMAP_SUBERBLOCK_EXPORTED 1	/* Notify that kernel provides it */
+#define BITMAP_MAGIC 0x6d746962		/* This is actually "bitm" in ASCII :-) */
+#define BITMAP_MAJOR_LO 3
+/* version 4 insists the bitmap is in little-endian order
+ * with version 3, it is host-endian which is non-portable
+ */
+#define BITMAP_MAJOR_HI 4
+#define BITMAP_MAJOR_CLUSTERED 5
+#define BITMAP_MAJOR_HOSTENDIAN 3
+
+/* use these for bitmap->flags and bitmap->sb->state bit-fields */
+enum bitmap_state {
+	BITMAP_STALE	   = 1,  /* the bitmap file is out of date or had -EIO */
+	BITMAP_WRITE_ERROR = 2, /* A write error has occurred */
+	BITMAP_HOSTENDIAN  = 15,
+};
+
+/* the superblock at the front of the bitmap file -- little endian */
+struct bitmap_super {
+	__le32 magic;        /*  0  BITMAP_MAGIC */
+	__le32 version;      /*  4  the bitmap major for now, could change... */
+	__u8  uuid[16];      /*  8  128 bit uuid - must match md device uuid */
+	__le64 events;       /* 24  event counter for the bitmap (1)*/
+	__le64 events_cleared;/*32  event counter when last bit cleared (2) */
+	__le64 sync_size;    /* 40  the size of the md device's sync range(3) */
+	__le32 state;        /* 48  bitmap state information */
+	__le32 chunksize;    /* 52  the bitmap chunk size in bytes */
+	__le32 daemon_sleep; /* 56  seconds between disk flushes */
+	__le32 write_behind; /* 60  number of outstanding write-behind writes */
+	__le32 sectors_reserved; /* 64 number of 512-byte sectors that are
+				  * reserved for the bitmap.
+				  */
+	__le32 nodes;        /* 68 the maximum number of nodes in cluster. */
+	__u8 cluster_name[64]; /* 72 cluster name to which this md belongs */
+	__u8  pad[256 - 136]; /* set to zero */
+} __attribute__ ((__packed__));
+
+/* notes:
+ * (1) This event counter is updated before the eventcounter in the md superblock
+ *    When a bitmap is loaded, it is only accepted if this event counter is equal
+ *    to, or one greater than, the event counter in the superblock.
+ * (2) This event counter is updated when the other one is *if*and*only*if* the
+ *    array is not degraded.  As bits are not cleared when the array is degraded,
+ *    this represents the last time that any bits were cleared.
+ *    If a device is being added that has an event count with this value or
+ *    higher, it is accepted as conforming to the bitmap.
+ * (3)This is the number of sectors represented by the bitmap, and is the range that
+ *    resync happens across.  For raid1 and raid5/6 it is the size of individual
+ *    devices.  For raid10 it is the size of the array.
+ */
+
 #endif
-- 
2.48.1

Re: [PATCH v4] Export MDRAID bitmap on disk structure in UAPI header file

[Christoph Hellwig]

On Tue, Feb 18, 2025 at 12:38:49PM +0100, Tomas Mudrunka wrote:
> When working on software that manages MD RAID disks from
> userspace. Currently provided headers only contain MD superblock.
> That is not enough to fully populate MD RAID metadata.
> Therefore this patch adds bitmap superblock as well.

And despite multiple resends this still is not a userspace ABI in any
sense of the word.  Just copy the header defining the stable on-disk
format.