107 lines
4.3 KiB
Diff
107 lines
4.3 KiB
Diff
|
From 256edaef3d43a112356762aaea4a48f021f45aec Mon Sep 17 00:00:00 2001
|
||
|
|
From: Mariusz Tkaczyk <mariusz.tkaczyk@linux.intel.com>
|
||
|
|
Date: Tue, 26 Mar 2024 13:21:12 +0100
|
||
|
|
Subject: [PATCH 50/69] mdadm: Add README.md
|
||
|
|
|
||
|
|
Describe supported metadata types, add step-by-step patch sending
|
||
|
|
instruction, mention minimally supported kernel version and licensing.
|
||
|
|
|
||
|
|
Signed-off-by: Mariusz Tkaczyk <mariusz.tkaczyk@linux.intel.com>
|
||
|
|
---
|
||
|
|
README.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||
|
|
1 file changed, 83 insertions(+)
|
||
|
|
create mode 100644 README.md
|
||
|
|
|
||
|
|
diff --git a/README.md b/README.md
|
||
|
|
new file mode 100644
|
||
|
|
index 00000000..64f2ecec
|
||
|
|
--- /dev/null
|
||
|
|
+++ b/README.md
|
||
|
|
@@ -0,0 +1,83 @@
|
||
|
|
+**mdadm** is a utility used to create and manage **software RAID** devices implemented through
|
||
|
|
+**Multiple devices driver (MD)** in kernel. It supports following RAID metadata formats:
|
||
|
|
+
|
||
|
|
+* [Linux native RAID](https://raid.wiki.kernel.org/index.php/RAID_superblock_formats):
|
||
|
|
+
|
||
|
|
+ Known as **native** or **native RAID**. First and default metadata format. Metadata management
|
||
|
|
+ is implemented in **MD driver**.
|
||
|
|
+
|
||
|
|
+* Matrix Storage Manager Support (no reference, metadata format documentation is proprietary).
|
||
|
|
+
|
||
|
|
+ Known as **IMSM**. Metadata format developed and maintained by **Intel®** as a part of **VROC**
|
||
|
|
+ solution. There are some functional differences between **native** and **imsm**. The most
|
||
|
|
+ important difference is that the metadata is managed from userspace.
|
||
|
|
+
|
||
|
|
+ **CAUTION:** **imsm** is compatible with **Intel RST**, however it is not officially supported.
|
||
|
|
+ You are using it on your own risk.
|
||
|
|
+
|
||
|
|
+* [Common RAID DDF Specification Revision](https://www.snia.org/sites/default/files/SNIA_DDF_Technical_Position_v2.0.pdf)
|
||
|
|
+
|
||
|
|
+ **IMPORTANT:** DDF is in **maintenance only** mode. There is no active development around it.
|
||
|
|
+ Please do not use it in new solutions.
|
||
|
|
+
|
||
|
|
+# How to Contribute
|
||
|
|
+
|
||
|
|
+ **mdadm** is hosted on [kernel.org](https://kernel.org/). You can access repository
|
||
|
|
+[here](https://git.kernel.org/pub/scm/utils/mdadm/mdadm.git).
|
||
|
|
+
|
||
|
|
+It is maintained similarly to kernel, using *mailing list*. Patches must be send through email.
|
||
|
|
+Please familiarize with general kernel
|
||
|
|
+[submitting patches](https://www.kernel.org/doc/html/v4.17/process/submitting-patches.html)
|
||
|
|
+documentation. Formatting, tags and commit message guidelines applies to **mdadm**.
|
||
|
|
+
|
||
|
|
+## Sending patches step-by-step
|
||
|
|
+
|
||
|
|
+To maximize change of patches being taken, follow this instruction when submitting:
|
||
|
|
+
|
||
|
|
+1. Create possibly logically separated commits and generate patches:
|
||
|
|
+
|
||
|
|
+ Use ``git format-patch --cover-letter --signoff -v <nr>`` to create patches:
|
||
|
|
+ * ``--cover-letter`` can be skipped if it is only one patch;
|
||
|
|
+ * ``--signoff`` adds sign-off tag;
|
||
|
|
+ * ``-v <nr>`` indicates review revision number, sender should increment it before resending.
|
||
|
|
+
|
||
|
|
+2. Check style of every patch with kernel
|
||
|
|
+ [checkpatch](https://docs.kernel.org/dev-tools/checkpatch.html) script:
|
||
|
|
+
|
||
|
|
+ It is important to keep same coding style that is why in **mdadm**
|
||
|
|
+ [kernel coding style](https://www.kernel.org/doc/html/v4.10/process/coding-style.html)
|
||
|
|
+ is preferred. ``checkpath --no-tree <patch_file>`` can be used to verify patches.
|
||
|
|
+ Following checkpatch issues can be ignored:
|
||
|
|
+ - New typedefs.
|
||
|
|
+ - comparing with *True/False*.
|
||
|
|
+ - kernel *MAINTAINERS* file warning.
|
||
|
|
+ - *extern* keyword in headers.
|
||
|
|
+
|
||
|
|
+3. Send patches using ``git send-mail --to=linux-raid@vger.kernel.org <cover-letter> <patch1> <patch2> (...)``
|
||
|
|
+
|
||
|
|
+# Maintainers
|
||
|
|
+
|
||
|
|
+It is good practice to add **mdadm maintainers** to recipients for patches:
|
||
|
|
+
|
||
|
|
+- Jes Sorensen <jes@trained-monkey.org>;
|
||
|
|
+- Mariusz Tkaczyk <mariusz.tkaczyk@linux.intel.com>;
|
||
|
|
+
|
||
|
|
+Adding **MD maintainers** could be reasonable, especially if patches may affect MD driver:
|
||
|
|
+
|
||
|
|
+- Song Liu <song@kernel.org>;
|
||
|
|
+- Yu Kuai <yukuai3@huawei.com>;
|
||
|
|
+
|
||
|
|
+# Reviewers
|
||
|
|
+
|
||
|
|
+**mdadm** utility is not part of kernel tree, so there is no certificated *Reviewers* list. Everyone
|
||
|
|
+can comment on mailing list, last decision (and merging) belongs to maintainers.
|
||
|
|
+
|
||
|
|
+# Minimal supported kernel version
|
||
|
|
+
|
||
|
|
+We do not support kernel versions below **v3.10**. Please be aware that maintainers may remove
|
||
|
|
+workarounds and fixes for legacy issues.
|
||
|
|
+
|
||
|
|
+# License
|
||
|
|
+
|
||
|
|
+It is released under the terms of the **GNU General Public License version 2** as published
|
||
|
|
+by the **Free Software Foundation**.
|
||
|
|
--
|
||
|
|
2.41.0
|
||
|
|
|