From bb636547b02411ca5eef87b1d030ea3fc090a717 Mon Sep 17 00:00:00 2001 From: NeilBrown Date: Tue, 8 Nov 2005 21:39:45 -0800 Subject: [PATCH] md: document sysfs usage of md, and make a couple of small refinements Document in Documentation/md.txt the files that now appear in sysfs, and make a couple of small refinements to exactly when 'level' and 'raid_disks' are empty, to make it match the documentation. Signed-off-by: Neil Brown Acked-by: Greg Kroah-Hartman Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/md.txt | 119 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) (limited to 'Documentation/md.txt') diff --git a/Documentation/md.txt b/Documentation/md.txt index e2b536992a27..23e6cce40f9c 100644 --- a/Documentation/md.txt +++ b/Documentation/md.txt @@ -116,3 +116,122 @@ and it's role in the array. Once started with RUN_ARRAY, uninitialized spares can be added with HOT_ADD_DISK. + + + +MD devices in sysfs +------------------- +md devices appear in sysfs (/sys) as regular block devices, +e.g. + /sys/block/md0 + +Each 'md' device will contain a subdirectory called 'md' which +contains further md-specific information about the device. + +All md devices contain: + level + a text file indicating the 'raid level'. This may be a standard + numerical level prefixed by "RAID-" - e.g. "RAID-5", or some + other name such as "linear" or "multipath". + If no raid level has been set yet (array is still being + assembled), this file will be empty. + + raid_disks + a text file with a simple number indicating the number of devices + in a fully functional array. If this is not yet known, the file + will be empty. If an array is being resized (not currently + possible) this will contain the larger of the old and new sizes. + +As component devices are added to an md array, they appear in the 'md' +directory as new directories named + dev-XXX +where XXX is a name that the kernel knows for the device, e.g. hdb1. +Each directory contains: + + block + a symlink to the block device in /sys/block, e.g. + /sys/block/md0/md/dev-hdb1/block -> ../../../../block/hdb/hdb1 + + super + A file containing an image of the superblock read from, or + written to, that device. + + state + A file recording the current state of the device in the array + which can be a comma separated list of + faulty - device has been kicked from active use due to + a detected fault + in_sync - device is a fully in-sync member of the array + spare - device is working, but not a full member. + This includes spares that are in the process + of being recoverred to + This list make grow in future. + + +An active md device will also contain and entry for each active device +in the array. These are named + + rdNN + +where 'NN' is the possition in the array, starting from 0. +So for a 3 drive array there will be rd0, rd1, rd2. +These are symbolic links to the appropriate 'dev-XXX' entry. +Thus, for example, + cat /sys/block/md*/md/rd*/state +will show 'in_sync' on every line. + + + +Active md devices for levels that support data redundancy (1,4,5,6) +also have + + sync_action + a text file that can be used to monitor and control the rebuild + process. It contains one word which can be one of: + resync - redundancy is being recalculated after unclean + shutdown or creation + recover - a hot spare is being built to replace a + failed/missing device + idle - nothing is happening + check - A full check of redundancy was requested and is + happening. This reads all block and checks + them. A repair may also happen for some raid + levels. + repair - A full check and repair is happening. This is + similar to 'resync', but was requested by the + user, and the write-intent bitmap is NOT used to + optimise the process. + + This file is writable, and each of the strings that could be + read are meaningful for writing. + + 'idle' will stop an active resync/recovery etc. There is no + guarantee that another resync/recovery may not be automatically + started again, though some event will be needed to trigger + this. + 'resync' or 'recovery' can be used to restart the + corresponding operation if it was stopped with 'idle'. + 'check' and 'repair' will start the appropriate process + providing the current state is 'idle'. + + mismatch_count + When performing 'check' and 'repair', and possibly when + performing 'resync', md will count the number of errors that are + found. The count in 'mismatch_cnt' is the number of sectors + that were re-written, or (for 'check') would have been + re-written. As most raid levels work in units of pages rather + than sectors, this my be larger than the number of actual errors + by a factor of the number of sectors in a page. + +Each active md device may also have attributes specific to the +personality module that manages it. +These are specific to the implementation of the module and could +change substantially if the implementation changes. + +These currently include + + stripe_cache_size (currently raid5 only) + number of entries in the stripe cache. This is writable, but + there are upper and lower limits (32768, 16). Default is 128. + strip_cache_active (currently raid5 only) + number of active entries in the stripe cache -- cgit v1.2.3