Date: Thu, 23 Apr 2026 20:29:07 +0000 From: Alexander Ziaee <ziaee@FreeBSD.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org Subject: git: 7ac7604b9141 - stable/15 - geom manuals: Clarify units Message-ID: <69ea8113.256c3.68ca5f8c@gitrepo.freebsd.org>
index | next in thread | raw e-mail
The branch stable/15 has been updated by ziaee: URL: https://cgit.FreeBSD.org/src/commit/?id=7ac7604b9141005cc0663a5d021bceaf7746e940 commit 7ac7604b9141005cc0663a5d021bceaf7746e940 Author: Alexander Ziaee <ziaee@FreeBSD.org> AuthorDate: 2026-04-20 17:21:23 +0000 Commit: Alexander Ziaee <ziaee@FreeBSD.org> CommitDate: 2026-04-23 20:28:54 +0000 geom manuals: Clarify units The gpart manual says that sizes are specified in blocks, unless an SI unit suffix is provided. This confuses new operators because GEOM uses binary bytes, a large difference at modern storage pool sizes. Rewrite suffixes in all GEOM manuals to consistently clarify this, matching what we and the rest of the industry have been doing in other documentation. While here, use non-breaking spaces between numbers and units, unless they are already written with a hyphen. MFC after: 3 days Reviewed by: fuz Reported by: bbaovanc <bbaovanc@bbaovanc.com> Differential Revision: https://reviews.freebsd.org/D56534 (cherry picked from commit 975e3605ebb15cbaf5a25c1c9d1f51aed41291d0) --- lib/geom/cache/gcache.8 | 4 ++-- lib/geom/eli/geli.8 | 8 +++---- lib/geom/part/gpart.8 | 52 ++++++++++++++++++++++++++-------------------- sbin/ggate/ggatec/ggatec.8 | 8 +++---- sbin/ggate/ggated/ggated.8 | 4 ++-- 5 files changed, 41 insertions(+), 35 deletions(-) diff --git a/lib/geom/cache/gcache.8 b/lib/geom/cache/gcache.8 index 026c66b0966b..072f35e92c01 100644 --- a/lib/geom/cache/gcache.8 +++ b/lib/geom/cache/gcache.8 @@ -82,9 +82,9 @@ The utility is used to control GEOM cache, which can speed up read performance by sending fixed size read requests to its consumer. It has been developed to address -the problem of a horrible read performance of a 64k blocksize FS +the problem of a horrible read performance of a 64\~KiB blocksize FS residing on a RAID3 array with 8 data components, where a single -disk component would only get 8k read requests, thus effectively +disk component would only get 8\~KiB read requests, thus effectively killing disk performance under high load. .Pp Caching can be configured using two different methods: diff --git a/lib/geom/eli/geli.8 b/lib/geom/eli/geli.8 index 876caf67ab40..b38f54d82293 100644 --- a/lib/geom/eli/geli.8 +++ b/lib/geom/eli/geli.8 @@ -249,7 +249,7 @@ Additional options include: .It Fl a Ar aalgo Enable data integrity verification (authentication) using the given algorithm. This will reduce the size of storage available and also reduce speed. -For example, when using 4096 bytes sector and +For example, when using 4096\~bytes sector and .Nm HMAC/SHA256 algorithm, 89% of the original provider storage will be available for use. Currently supported algorithms are: @@ -883,8 +883,8 @@ The crypto card and the driver have to support this feature. .It Va kern.geom.eli.key_cache_limit : No 8192 Specifies how many Data Keys to cache. The default limit -(8192 keys) will allow caching of all keys for a 4TB provider with 512 byte -sectors and will take around 1MB of memory. +(8192 keys) will allow caching of all keys for a 4\~TiB provider with 512\~byte +sectors and will take around 1\~MiB of memory. .It Va kern.geom.eli.key_cache_hits Reports how many times we were looking up a Data Key and it was already in cache. @@ -936,7 +936,7 @@ Exit status is 0 on success, and 1 if the command fails. .Sh EXAMPLES Initialize a provider which is going to be encrypted with a passphrase and random data from a file on the user's pen drive. -Use 4kB sector size. +Use 4\~KiB sector size. Attach the provider, create a filesystem, and mount it. Do the work. Unmount the provider and detach it: diff --git a/lib/geom/part/gpart.8 b/lib/geom/part/gpart.8 index 97dd60182435..32a247529dfe 100644 --- a/lib/geom/part/gpart.8 +++ b/lib/geom/part/gpart.8 @@ -22,7 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd December 4, 2025 +.Dd April 20, 2026 .Dt GPART 8 .Os .Sh NAME @@ -168,7 +168,9 @@ to be multiple of value. .It Fl b Ar start The logical block address where the partition will begin. -An SI unit suffix is allowed. +A single-character suffix +.Pq k, m, g, etc. +is allowed to specify binary byte sizes. .It Fl f Ar flags Additional operational flags. See the section entitled @@ -187,7 +189,9 @@ partition labels. .It Fl s Ar size Create a partition of size .Ar size . -An SI unit suffix is allowed. +A single-character suffix +.Pq k, m, g, etc. +is allowed to specify binary byte sizes. .It Fl t Ar type Create a partition of type .Ar type . @@ -422,8 +426,10 @@ about its use. .It Fl i Ar index Specifies the index of the partition to be resized. .It Fl s Ar size -Specifies the new size of the partition, in logical blocks. -An SI unit suffix is allowed. +Specifies the new size of the partition, in logical blocks, +or binary byte sizes if a single-character suffix +.Pq k, m, g, etc. +is provided. .El .\" ==== RESTORE ==== .It Cm restore @@ -1134,7 +1140,7 @@ with type (see the .Sx "PARTITION TYPES" section). -It uses 8 KB size bootstrap code image +It uses 8\~KiB size bootstrap code image .Pa /boot/boot , embedded into the partition table's metadata area. .Pp @@ -1149,7 +1155,7 @@ partition (see the section) and runs the next bootstrap stage from it. The .Cm freebsd-boot -partition should be smaller than 545 KB. +partition should be smaller than 545\~KiB. It can be located either before or after other .Fx partitions on the disk. @@ -1190,13 +1196,13 @@ After all pools are detected, is started from the first one found set as bootable. .Pp The APM scheme also does not support embedding bootstrap code. -Instead, the 800 KBytes bootstrap code image +Instead, the 800\~KiB bootstrap code image .Pa /boot/boot1.hfs should be written with the .Cm gpart bootcode command to a partition of type .Cm apple-boot , -which should also be 800 KB in size. +which should also be 800\~KiB in size. .Sh OPERATIONAL FLAGS Actions other than the .Cm commit @@ -1351,8 +1357,8 @@ naming scheme. .Sh EXIT STATUS Exit status is 0 on success, and 1 if the command fails. .Sh EXAMPLES -The examples below assume that the disk's logical block size is 512 -bytes, regardless of its physical block size. +The examples below assume that the disk's logical block size is 512\~bytes, +regardless of its physical block size. .Ss GPT In this example, we will format .Pa ada0 @@ -1384,31 +1390,31 @@ for UFS or .Pa /boot/gptzfsboot for ZFS .Pc , -but smaller than 545 kB since the first-stage loader will load the +but smaller than 545\~KiB since the first-stage loader will load the entire partition into memory during boot, regardless of how much data it actually contains. -We create a 472-block (236 kB) boot partition at offset 40, which is -the size of the partition table (34 blocks or 17 kB) rounded up to the -nearest 4 kB boundary. +We create a 472-block (236\~KiB) boot partition at offset 40, which is +the size of the partition table (34\~blocks or 17\~KiB) rounded up to the +nearest 4\~KiB boundary. .Bd -literal -offset indent /sbin/gpart add -b 40 -s 472 -t freebsd-boot ada0 /sbin/gpart bootcode -p /boot/gptboot -i 1 ada0 .Ed .Pp -We now create a 4 GB swap partition at the first available offset, -which is 40 + 472 = 512 blocks (256 kB). +We now create a 4\~GiB swap partition at the first available offset, +which is 40 + 472 = 512 blocks (256\~KiB). .Bd -literal -offset indent /sbin/gpart add -s 4G -t freebsd-swap ada0 .Ed .Pp -Aligning the swap partition and all subsequent partitions on a 256 kB +Aligning the swap partition and all subsequent partitions on a 256\~KiB boundary ensures optimal performance on a wide range of media, from plain old disks with 512-byte blocks, through modern .Dq advanced format disks with 4096-byte physical blocks, to RAID volumes with stripe -sizes of up to 256 kB. +sizes of up to 256\~KiB. .Pp -Finally, we create and format an 8 GB +Finally, we create and format an 8\~GiB .Cm freebsd-ufs partition for the root filesystem, leaving the rest of the device free for additional filesystems: @@ -1424,8 +1430,8 @@ using a traditional .Bx disklabel. .Pp -First, we create the partition table as well as a single partition 64 GB in -size and an alignment of 4 kB, then we mark that partition active (bootable) +First, we create the partition table as well as a single partition 64\~GiB in +size and an alignment of 4\~KiB, then we mark that partition active (bootable) and install the first-stage boot loader: .Bd -literal -offset indent /sbin/gpart create -s MBR ada0 @@ -1444,7 +1450,7 @@ with room for up to 20 partitions: /sbin/gpart create -s BSD -n 20 ada0s1 .Ed .Pp -We then create an 8 GB root partition and a 4 GB swap partition: +We then create an 8\~GiB root partition and a 4\~GiB swap partition: .Bd -literal -offset indent /sbin/gpart add -t freebsd-ufs -s 8G ada0s1 /sbin/gpart add -t freebsd-swap -s 4G ada0s1 diff --git a/sbin/ggate/ggatec/ggatec.8 b/sbin/ggate/ggatec/ggatec.8 index 99f9bcab5964..b8c5af570f06 100644 --- a/sbin/ggate/ggatec/ggatec.8 +++ b/sbin/ggate/ggatec/ggatec.8 @@ -101,7 +101,7 @@ providers. .El .Pp Available options: -.Bl -tag -width ".Fl s Cm ro | wo | rw" +.Bl -tag -width "-q queue_size" .It Fl f Forcibly destroy .Nm ggate @@ -136,15 +136,15 @@ start to be canceled. Default is 1024. .It Fl R Ar rcvbuf Size of receive buffer to use. -Default is 131072 (128kB). +Default is 131072 (128\~KiB). .It Fl S Ar sndbuf Size of send buffer to use. -Default is 131072 (128kB). +Default is 131072 (128\~KiB). .It Fl s Ar sectorsize Sector size for .Nm ggate provider. -If not specified, it is taken from the device, or set to 512 bytes for files. +If not specified, it is taken from the device, or set to 512\~bytes for files. .It Fl t Ar timeout Number of seconds to wait before an I/O request will be canceled. Default is 0, which means no timeout. diff --git a/sbin/ggate/ggated/ggated.8 b/sbin/ggate/ggated/ggated.8 index 8e3ad68d1db0..c48967268df8 100644 --- a/sbin/ggate/ggated/ggated.8 +++ b/sbin/ggate/ggated/ggated.8 @@ -72,10 +72,10 @@ PID file that uses. .It Fl R Ar rcvbuf Size of receive buffer to use. -Default is 131072 (128kB). +Default is 131072 (128\~KiB). .It Fl S Ar sndbuf Size of send buffer to use. -Default is 131072 (128kB). +Default is 131072 (128\~KiB). .It Fl v Do not fork, run in foreground and print debug information on standard output.home | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?69ea8113.256c3.68ca5f8c>