git: 32ef68b0f30d - stable/15 - geom_zero.4: Document
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Tue, 18 Nov 2025 13:38:55 UTC
The branch stable/15 has been updated by 0mp:
URL: https://cgit.FreeBSD.org/src/commit/?id=32ef68b0f30d903455173fc4c0029d4bced647db
commit 32ef68b0f30d903455173fc4c0029d4bced647db
Author: Mateusz Piotrowski <0mp@FreeBSD.org>
AuthorDate: 2025-11-09 14:46:40 +0000
Commit: Mateusz Piotrowski <0mp@FreeBSD.org>
CommitDate: 2025-11-18 13:38:48 +0000
geom_zero.4: Document
PR: 250593
Reviewed by: bcr, ziaee
Thanks to: imp, markj
MFC after: 1 week
Fixes: 3843eba85d98 Add unmapped BIO support to GEOM ZERO
Fixes: 24e1fdcd1a69 Allow to specify the byte which will be used for filling read buffer
Fixes: 565bc101112c Add a very simple and small GEOM class - ZERO
(cherry picked from commit 39acb7fd86eda721df402c2f1368b78cede161c3)
---
share/man/man4/Makefile | 2 +
share/man/man4/geom_zero.4 | 174 +++++++++++++++++++++++++++++++++++++++++++++
share/man/man4/zero.4 | 3 +-
3 files changed, 178 insertions(+), 1 deletion(-)
diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index dd98badd31ba..a04e20dfea27 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -189,6 +189,7 @@ MAN= aac.4 \
geom.4 \
geom_linux_lvm.4 \
geom_uzip.4 \
+ geom_zero.4 \
gif.4 \
${_gve.4} \
gpio.4 \
@@ -1120,6 +1121,7 @@ MAN+= \
veriexec.4 \
zyd.4
+MLINKS+=geom_zero.4 gzero.4
MLINKS+=mtw.4 if_mtw.4
MLINKS+=otus.4 if_otus.4
MLINKS+=rsu.4 if_rsu.4
diff --git a/share/man/man4/geom_zero.4 b/share/man/man4/geom_zero.4
new file mode 100644
index 000000000000..8da09b1473c9
--- /dev/null
+++ b/share/man/man4/geom_zero.4
@@ -0,0 +1,174 @@
+.\"
+.\" Copyright (c) 2019 Greg White <gkwhite@gmail.com>. All rights reserved.
+.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org>
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.Dd November 9, 2025
+.Dt GEOM_ZERO 4
+.Os
+.Sh NAME
+.Nm gzero ,
+.Nm geom_zero
+.Nd GEOM-based zero disk/block device
+.Sh SYNOPSIS
+.Cd "options GEOM_ZERO"
+.Pp
+In
+.Xr loader.conf 5
+or
+.Xr sysctl.conf 5 :
+.Cd kern.geom.zero.byte
+.Cd kern.geom.zero.clear
+.Sh DESCRIPTION
+.Nm
+is a
+.Xr GEOM 4
+device simulating a one-exabyte disk.
+It throws away any data written to it,
+and returns the value of
+.Va kern.geom.zero.byte
+for every byte read from it.
+.Pp
+.Nm
+differs from
+.Xr zero 4 ,
+which is a regular character device and has an infinite length,
+while
+.Pa /dev/gzero
+is a
+.Xr GEOM 4
+provider of large, but limited, size.
+.Pp
+Consult
+.Xr geom 8
+for instructions on how to use the supported commands of the
+.Xr GEOM 4
+.Nm ZERO
+class.
+.Pp
+.Nm
+is useful for benchmarking performance of GEOM and GEOM classes
+where compression of the data does not affect the results
+.Po blocks from
+.Pa /dev/gzero
+compress exceptionally well
+.Pc .
+Examples of such benchmarks include
+comparing the speed of two disk encryption algorithms and
+comparing a hardware versus software implementation
+of a single encryption algorithm.
+.Sh MIB VARIABLES
+The following variables are available as both
+.Xr sysctl 8
+variables and
+.Xr loader 8
+tunables:
+.Bl -tag -width "kern.geom.zero.clear"
+.It Va kern.geom.zero.byte
+This variable sets the fill byte of the
+.Nm
+device.
+Default:
+.Ql 0 .
+.It Va kern.geom.zero.clear
+This variable controls the clearing of the read data buffer.
+If set to
+.Ql 0 ,
+.Nm
+will not copy any data into the read data buffers
+and just return the read data buffers as they are without modifying them.
+In particular, it will not not fill the read buffer with the value of
+.Va kern.geom.zero.byte .
+This is useful for read benchmarking to reduce the measurement noise
+caused by extra memory initialization.
+Default:
+.Ql 1 .
+.El
+.Sh FILES
+.Bl -tag -width /dev/gzero
+.It Pa /dev/gzero
+The
+.Nm
+device.
+.El
+.Sh EXAMPLES
+Create the
+.Pa /dev/gzero
+device by loading the
+.Nm geom_zero
+kernel module:
+.Bd -literal -offset indent
+# geom zero load
+.Ed
+.Pp
+Show information about the
+.Nm
+device:
+.Bd -literal -offset indent
+# geom zero list
+Geom name: gzero
+Providers:
+1. Name: gzero
+ Mediasize: 1152921504606846976 (1.0E)
+ Sectorsize: 512
+ Mode: r0w0egzero0
+.Ed
+.Pp
+Set the fill byte of the
+.Nm
+device to 70
+.Po decimal for letter
+.Dq F
+in
+.Xr ascii 7
+.Pc :
+.Bd -literal -offset indent
+# sysctl kern.geom.zero.byte=70
+kern.geom.zero.byte: 0 -> 70
+# head -c 1 /dev/gzero
+F
+.Ed
+.Pp
+Benchmark read and write throughput of
+.Xr geli 8 Ap s
+default encryption algorithm with a 4-KiB sector size:
+.Bd -literal -offset indent
+# geom zero load
+# geli onetime -s 4096 gzero
+# sysctl kern.geom.zero.clear=0
+# dd if=/dev/gzero.eli of=/dev/zero bs=4k count=$((1024 * 256))
+262144+0 records in
+262144+0 records out
+1073741824 bytes transferred in 1.258195 secs (853398307 bytes/sec)
+# dd if=/dev/zero of=/dev/gzero.eli bs=4k count=$((1024 * 256))
+262144+0 records in
+262144+0 records out
+1073741824 bytes transferred in 1.663118 secs (645619658 bytes/sec)
+.Ed
+.Sh SEE ALSO
+.Xr GEOM 4 ,
+.Xr zero 4 ,
+.Xr geom 8 ,
+.Xr sysctl 8 ,
+.Xr bio 9
+.Sh HISTORY
+A
+.Nm
+device first appeared in
+.Fx 6 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm
+device was written by
+.An Paweł Jakub Dawidek Aq Mt pjd@FreeBSD.org .
+.Pp
+The
+.Nm
+manual page was originally written by
+.An Greg White Aq Mt gkwhite@gmail.com
+and rewritten by
+.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org
+before landing in
+.Fx .
diff --git a/share/man/man4/zero.4 b/share/man/man4/zero.4
index f1cd52d455d1..85651d53d342 100644
--- a/share/man/man4/zero.4
+++ b/share/man/man4/zero.4
@@ -29,7 +29,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd April 7, 1996
+.Dd November 9, 2025
.Dt ZERO 4
.Os
.Sh NAME
@@ -48,6 +48,7 @@ supply of null bytes when read.
.El
.Sh SEE ALSO
.Xr full 4 ,
+.Xr gzero 4 ,
.Xr null 4
.Sh HISTORY
A