1
0
mirror of https://git.FreeBSD.org/src.git synced 2026-06-02 11:24:32 +00:00

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
This commit is contained in:
Alexander Ziaee
2026-04-20 13:21:23 -04:00
parent 374548e930
commit 975e3605eb
5 changed files with 41 additions and 35 deletions
+2 -2
View File
@@ -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:
+4 -4
View File
@@ -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:
+29 -23
View File
@@ -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
+4 -4
View File
@@ -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.
+2 -2
View File
@@ -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.