Skip to content

Commit 39acb7f

Browse files
0mp0mp
committed
geom_zero.4: Document
PR: 250593 Reviewed by: bcr, ziaee Thanks to: imp, markj MFC after: 1 week Fixes: 3843eba Add unmapped BIO support to GEOM ZERO Fixes: 24e1fdc Allow to specify the byte which will be used for filling read buffer Fixes: 565bc10 Add a very simple and small GEOM class - ZERO
1 parent b3b279b commit 39acb7f

File tree

3 files changed

+178
-1
lines changed

3 files changed

+178
-1
lines changed

‎share/man/man4/Makefile‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -189,6 +189,7 @@ MAN= aac.4 \
189189
geom.4 \
190190
geom_linux_lvm.4 \
191191
geom_uzip.4 \
192+
geom_zero.4 \
192193
gif.4 \
193194
${_gve.4} \
194195
gpio.4 \
@@ -1123,6 +1124,7 @@ MAN+= \
11231124
veriexec.4 \
11241125
zyd.4
11251126

1127+
MLINKS+=geom_zero.4 gzero.4
11261128
MLINKS+=mtw.4 if_mtw.4
11271129
MLINKS+=otus.4 if_otus.4
11281130
MLINKS+=rsu.4 if_rsu.4

‎share/man/man4/geom_zero.4‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
.\"
2+
.\" Copyright (c) 2019 Greg White <[email protected]>. All rights reserved.
3+
.\" Copyright (c) 2025 Mateusz Piotrowski <[email protected]>
4+
.\"
5+
.\" SPDX-License-Identifier: BSD-2-Clause
6+
.\"
7+
.Dd November 9, 2025
8+
.Dt GEOM_ZERO 4
9+
.Os
10+
.Sh NAME
11+
.Nm gzero ,
12+
.Nm geom_zero
13+
.Nd GEOM-based zero disk/block device
14+
.Sh SYNOPSIS
15+
.Cd "options GEOM_ZERO"
16+
.Pp
17+
In
18+
.Xr loader.conf 5
19+
or
20+
.Xr sysctl.conf 5 :
21+
.Cd kern.geom.zero.byte
22+
.Cd kern.geom.zero.clear
23+
.Sh DESCRIPTION
24+
.Nm
25+
is a
26+
.Xr GEOM 4
27+
device simulating a one-exabyte disk.
28+
It throws away any data written to it,
29+
and returns the value of
30+
.Va kern.geom.zero.byte
31+
for every byte read from it.
32+
.Pp
33+
.Nm
34+
differs from
35+
.Xr zero 4 ,
36+
which is a regular character device and has an infinite length,
37+
while
38+
.Pa /dev/gzero
39+
is a
40+
.Xr GEOM 4
41+
provider of large, but limited, size.
42+
.Pp
43+
Consult
44+
.Xr geom 8
45+
for instructions on how to use the supported commands of the
46+
.Xr GEOM 4
47+
.Nm ZERO
48+
class.
49+
.Pp
50+
.Nm
51+
is useful for benchmarking performance of GEOM and GEOM classes
52+
where compression of the data does not affect the results
53+
.Po blocks from
54+
.Pa /dev/gzero
55+
compress exceptionally well
56+
.Pc .
57+
Examples of such benchmarks include
58+
comparing the speed of two disk encryption algorithms and
59+
comparing a hardware versus software implementation
60+
of a single encryption algorithm.
61+
.Sh MIB VARIABLES
62+
The following variables are available as both
63+
.Xr sysctl 8
64+
variables and
65+
.Xr loader 8
66+
tunables:
67+
.Bl -tag -width "kern.geom.zero.clear"
68+
.It Va kern.geom.zero.byte
69+
This variable sets the fill byte of the
70+
.Nm
71+
device.
72+
Default:
73+
.Ql 0 .
74+
.It Va kern.geom.zero.clear
75+
This variable controls the clearing of the read data buffer.
76+
If set to
77+
.Ql 0 ,
78+
.Nm
79+
will not copy any data into the read data buffers
80+
and just return the read data buffers as they are without modifying them.
81+
In particular, it will not not fill the read buffer with the value of
82+
.Va kern.geom.zero.byte .
83+
This is useful for read benchmarking to reduce the measurement noise
84+
caused by extra memory initialization.
85+
Default:
86+
.Ql 1 .
87+
.El
88+
.Sh FILES
89+
.Bl -tag -width /dev/gzero
90+
.It Pa /dev/gzero
91+
The
92+
.Nm
93+
device.
94+
.El
95+
.Sh EXAMPLES
96+
Create the
97+
.Pa /dev/gzero
98+
device by loading the
99+
.Nm geom_zero
100+
kernel module:
101+
.Bd -literal -offset indent
102+
# geom zero load
103+
.Ed
104+
.Pp
105+
Show information about the
106+
.Nm
107+
device:
108+
.Bd -literal -offset indent
109+
# geom zero list
110+
Geom name: gzero
111+
Providers:
112+
1. Name: gzero
113+
Mediasize: 1152921504606846976 (1.0E)
114+
Sectorsize: 512
115+
Mode: r0w0egzero0
116+
.Ed
117+
.Pp
118+
Set the fill byte of the
119+
.Nm
120+
device to 70
121+
.Po decimal for letter
122+
.Dq F
123+
in
124+
.Xr ascii 7
125+
.Pc :
126+
.Bd -literal -offset indent
127+
# sysctl kern.geom.zero.byte=70
128+
kern.geom.zero.byte: 0 -> 70
129+
# head -c 1 /dev/gzero
130+
F
131+
.Ed
132+
.Pp
133+
Benchmark read and write throughput of
134+
.Xr geli 8 Ap s
135+
default encryption algorithm with a 4-KiB sector size:
136+
.Bd -literal -offset indent
137+
# geom zero load
138+
# geli onetime -s 4096 gzero
139+
# sysctl kern.geom.zero.clear=0
140+
# dd if=/dev/gzero.eli of=/dev/zero bs=4k count=$((1024 * 256))
141+
262144+0 records in
142+
262144+0 records out
143+
1073741824 bytes transferred in 1.258195 secs (853398307 bytes/sec)
144+
# dd if=/dev/zero of=/dev/gzero.eli bs=4k count=$((1024 * 256))
145+
262144+0 records in
146+
262144+0 records out
147+
1073741824 bytes transferred in 1.663118 secs (645619658 bytes/sec)
148+
.Ed
149+
.Sh SEE ALSO
150+
.Xr GEOM 4 ,
151+
.Xr zero 4 ,
152+
.Xr geom 8 ,
153+
.Xr sysctl 8 ,
154+
.Xr bio 9
155+
.Sh HISTORY
156+
A
157+
.Nm
158+
device first appeared in
159+
.Fx 6 .
160+
.Sh AUTHORS
161+
.An -nosplit
162+
The
163+
.Nm
164+
device was written by
165+
.An Paweł Jakub Dawidek Aq Mt [email protected] .
166+
.Pp
167+
The
168+
.Nm
169+
manual page was originally written by
170+
.An Greg White Aq Mt [email protected]
171+
and rewritten by
172+
.An Mateusz Piotrowski Aq Mt [email protected]
173+
before landing in
174+
.Fx .

‎share/man/man4/zero.4‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@
2929
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
3030
.\" SUCH DAMAGE.
3131
.\"
32-
.Dd April 7, 1996
32+
.Dd November 9, 2025
3333
.Dt ZERO 4
3434
.Os
3535
.Sh NAME
@@ -48,6 +48,7 @@ supply of null bytes when read.
4848
.El
4949
.Sh SEE ALSO
5050
.Xr full 4 ,
51+
.Xr gzero 4 ,
5152
.Xr null 4
5253
.Sh HISTORY
5354
A

0 commit comments

Comments
 (0)