Document disk ioctl

First stab at documenting the different disk ioctl commands defined in
sys/disk.h.

Reviewed by: phk (prior version)
Differential Revision: https://reviews.freebsd.org/D26994

2 files changed, 211 insertions, 0 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index c4647c7d4b56..3f171789a73d 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -130,6 +130,7 @@ MAN=	aac.4 \
 	ddb.4 \
 	devctl.4 \
 	disc.4 \
+	disk.4 \
 	divert.4 \
 	${_dpms.4} \
 	ds1307.4 \
diff --git a/share/man/man4/disk.4 b/share/man/man4/disk.4
new file mode 100644
index 000000000000..69796059fc1e
--- /dev/null
+++ b/share/man/man4/disk.4
@@ -0,0 +1,210 @@
+.\" Copyright (c) 2020 M. Warner Losh <imp@FreeBSD.org>
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd November 20, 2020
+.Dt disk 4
+.Os
+.Sh NAME
+.Nm disk
+.Nd common disk interfaces
+.Sh SYNOPSIS
+.Cd device cd
+.Sh DESCRIPTION
+Common block device IOCTLs
+.Pp
+All the block devices in the system should support these disk
+.Xr ioctl 2
+commands defined here.
+Much of this information is also available via the
+.Xr geom 2
+attributes.
+.Sh IOCTLS
+The following
+.Xr ioctl 2
+calls apply to disk drives, and are defined
+in the
+.In sys/disk.h
+header file.
+.Bl -tag -width DIOCGPROVIDERNAME
+.It Dv DIOCGSECTORSIZE
+.Pq Li "u_int"
+Get the sector or block size of the device in bytes.
+The sector size is the smallest unit of data which can be transferred
+from this device.
+This is usually a power of 2 but it might not be (e.g. CDROM audio).
+Operations to block devices such as
+.Xr lseek 2 ,
+.Xr read 2 ,
+and
+.Xr write
+may only be performed at file offsets that are integral multiple of
+this size.
+.It Dv DIOCGMEDIASIZE
+.Pq Li "off_t"
+Get the size of the entire device in bytes.
+This should be a multiple of the sector size.
+.It Dv DIOCGFWSECTORS
+.Pq Li "u_int"
+Return the firmware's notion of number of sectors per track.
+This value is mostly used for compatibility with various ill designed
+disk label formats.
+Use this value only when absolutely required.
+Its interpretation and use is largely obsolete.
+.It Dv DIOCGFWHEADS
+.Pq Li "u_int"
+Return the firmware's notion of number of heads per cylinder.
+This value is mostly used for compatibility with various ill designed
+disk label formats.
+Use this value only when absolutely required.
+Its interpretation and use is largely obsolete.
+.It Dv DIOCGFLUSH
+Flush write cache of the device.
+.It Dv DIOCGDELETE
+.Pq Li "off_t[2]"
+Mark data on the device as unused.
+The first element is the offset to start deleting.
+The second element is the length to delete.
+Providers may use this information to free storage or instruct storage
+devices the contents can be discarded.
+.It Dv DIOCGIDENT
+.Pq Li "char[DISK_IDENT_SIZE]"
+Get the ident for this provider.
+Ident is a unique and fixed identifier for this provider.
+Ident's properties are as follow:
+.Bl -bullet
+.It
+preserved between reboots,
+.It
+preserved across a provider being detached/attached,
+.It
+provider's name can change - ident can't,
+.It
+ident value should not be based on on-disk metadata; in other
+words, copying whole data from one disk to another should not
+yield the same ident for the other disk,
+.It
+there can be more than one provider with the same ident, but
+only if they point at exactly the same physical storage, this is
+the case for multipathing for example,
+.It
+GEOM classes that consume a single provider and provide single
+provider, like
+.Xr geli 8 ,
+and
+.Xr gbde 8 ,
+the identifier should be formed by attaching that provider's class
+name to the ident of the underlying provider,
+.It
+ident is an NUL-terminated ASCII string (is printable),
+.It
+ident is optional and applications can't relay on its presence.
+.El
+.It Dv DIOCGPROVIDERNAME
+.Pq Li "char[MAXPATHLEN]"
+Store the provider name for the device in a buffer.
+The buffer must be at least MAXPATHLEN bytes long.
+.It Dv DIOCGSTRIPESIZE
+.Pq Li "off_t"
+Get the size of the device's optimal access block in bytes.
+This should be a multiple of the sector size.
+.It Dv DIOCGSTRIPEOFFSET
+.Pq Li "off_t"
+Get the offset of the first device's optimal access block in bytes.
+This should be a multiple of the sector size.
+.It Dv DIOCGPHYSPATH
+.Pq Li "char[MAXPATHLEN]"
+Get a string defining the physical path for a given provider.
+This has similar rules to ident, but is intended to uniquely
+identify the physical location of the device, not the current
+occupant of that location.
+The buffer must be at least MAXPATHLEN bytes long.
+.It Dv DIOCGATTR
+.Pq Li "struct diocgattr_arg"
+.Bd -literal -offset indent
+struct diocgattr_arg {
+	char name[64];
+	int len;
+	union {
+		char str[DISK_IDENT_SIZE];
+		off_t off;
+		int i;
+		uint16_t u16;
+	} value;
+};
+.Ed
+Get a geom attribute from the provider.
+Format of the returned data is specific to the attribute.
+.It Dv DIOCZONECMD
+.Pq Li "struct disk_zone_arg"
+Send disk zone commands.
+.It Dv DIOCSKERNELDUMP
+.Pq Li "struct diocskerneldump_arg"
+Enable/Disable the device for kernel core dumps.
+.It Dv DIOCGKERNELDUMP
+.Pq Li "struct diocskerneldump_arg"
+Get current kernel netdump configuration details for a given index.
+.Bd -literal -offset indent
+/*
+ * Sentinel values for kda_index.
+ *
+ * If kda_index is KDA_REMOVE_ALL, all dump configurations are cleared.
+ *
+ * If kda_index is KDA_REMOVE_DEV, all dump configurations for the specified
+ * device are cleared.
+ *
+ * If kda_index is KDA_REMOVE, only the specified dump configuration for the
+ * given device is removed from the list of fallback dump configurations.
+ *
+ * If kda_index is KDA_APPEND, the dump configuration is added after all
+ * existing dump configurations.
+ *
+ * Otherwise, the new configuration is inserted into the fallback dump list at
+ * index 'kda_index'.
+ */
+#define	KDA_REMOVE		UINT8_MAX
+#define	KDA_REMOVE_ALL		(UINT8_MAX - 1)
+#define	KDA_REMOVE_DEV		(UINT8_MAX - 2)
+#define	KDA_APPEND		(UINT8_MAX - 3)
+struct diocskerneldump_arg {
+	uint8_t		 kda_index;
+	uint8_t		 kda_compression;
+	uint8_t		 kda_encryption;
+	uint8_t		 kda_key[KERNELDUMP_KEY_MAX_SIZE];
+	uint32_t	 kda_encryptedkeysize;
+	uint8_t		*kda_encryptedkey;
+	char		 kda_iface[IFNAMSIZ];
+	union kd_ip	 kda_server;
+	union kd_ip	 kda_client;
+	union kd_ip	 kda_gateway;
+	uint8_t		 kda_af;
+};
+.Ed
+.El
+.Sh HISTORY
+The manual page was written by
+.An M Warner Losh Aq Mt imp@FreeBSD.org
+from text largely derived from
+.In sys/disk.h .