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