xref: /dragonfly/share/man/man4/md.4 (revision d4ef6694) 
1.\" ----------------------------------------------------------------------------
2.\" "THE BEER-WARE LICENSE" (Revision 42):
3.\" <phk@FreeBSD.ORG> wrote this file.  As long as you retain this notice you
4.\" can do whatever you want with this stuff. If we meet some day, and you think
5.\" this stuff is worth it, you can buy me a beer in return.   Poul-Henning Kamp
6.\" ----------------------------------------------------------------------------
7.\"
8.\" $FreeBSD: src/share/man/man4/md.4,v 1.3.2.4 2001/06/18 22:00:12 dd Exp $
9.\"
10.Dd September 28, 2009
11.Dt MD 4
12.Os
13.Sh NAME
14.Nm md
15.Nd memory disk
16.Sh SYNOPSIS
17To compile this driver into the kernel,
18place the following line in your
19kernel configuration file:
20.Bd -ragged -offset indent
21.Cd device md
22.Ed
23.Pp
24Alternatively, to load the driver as a module at boot time, place the
25following line in
26.Pa /boot/loader.conf :
27.Bd -literal -offset indent
28md_load="YES"
29.Ed
30.Pp
31To specify the default maximum size of
32.Xr kmalloc 9
33backed disks:
34.Cd options MD_NSECT=20000
35.Sh DESCRIPTION
36The
37.Nm
38driver provides support for two kinds of memory backed virtual disks:
39.Xr kmalloc 9
40backed
41and pre-loaded module backed.
42.Pp
43The
44.Xr kmalloc 9
45backed
46disks
47are severely limited in size by constraints imposed by
48.Xr kmalloc 9 .
49Specifically, only one malloc bucket is used, which means that all
50.Nm
51devices with
52.Xr kmalloc 9
53backing must share the malloc per-bucket quota.
54The exact size of this quota varies,
55in particular with the amount of RAM in the system.
56The exact value can be determined with
57.Xr vmstat 8 .
58.Pp
59A sector filled with identical bytes does not consume storage,
60and therefore the storage allocated by a
61.Nm
62disk can be freed with a command such as this:
63.Bd -literal -offset indent
64dd if=/dev/zero of=/dev/md567
65.Ed
66.Pp
67The default maximum size of a
68.Nm
69disk
70backed by
71.Xr kmalloc 9
72is 20,000 sectors of 512 bytes each.
73This can be changed
74with the kernel option
75.Dv MD_NSECT .
76.Pp
77At boot time the
78.Nm
79driver will search for pre-loaded modules of type
80.Sq md_image
81and instantiate a
82.Nm
83device for each of these modules.
84The type
85.Sq mfs_root
86is also allowed for backward compatibility.
87These devices are backed by the RAM reserved by the
88.Xr loader 8 ,
89and as such not limited by the
90.Xr kmalloc 9
91size constraints.
92However, this also means that the storage cannot be released.
93For the same reason,
94the
95.Dq identical byte
96detection is not applicable.
97.Pp
98The
99.Nm
100driver uses the
101.Dq almost-clone
102convention,
103whereby opening device number N creates device instance number N+1.
104.Pp
105The
106.Xr vmstat 8
107utility can be used to monitor memory usage by
108.Xr kmalloc 9
109backed
110.Nm
111disks,
112but not those backed by pre-loaded modules.
113.Sh EXAMPLES
114To mount a
115.Xr kmalloc 9
116backed
117.Nm
118device on
119.Pa /tmp :
120.Bd -literal
121if [ -e /dev/md0 ]; then
122	newfs /dev/md0 && \\
123	mount /dev/md0 /tmp && \\
124	chmod 1777 /tmp
125fi
126.Ed
127.Sh SEE ALSO
128.Xr disklabel 5 ,
129.Xr disklabel 8 ,
130.Xr fdisk 8 ,
131.Xr loader 8 ,
132.Xr newfs 8 ,
133.Xr vmstat 8
134.Sh HISTORY
135The
136.Nm
137driver first appeared in
138.Fx 4.0
139as a cleaner replacement
140for the MFS functionality previously used in PicoBSD
141and in the
142.Fx
143installation process.
144.Sh AUTHORS
145The
146.Nm
147driver was written by
148.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org .
149