svn commit: r367847 - head/share/man/man4
Warner Losh
imp at FreeBSD.org
Thu Nov 19 17:54:42 UTC 2020
Author: imp
Date: Thu Nov 19 17:54:41 2020
New Revision: 367847
URL: https://svnweb.freebsd.org/changeset/base/367847
Log:
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
Added:
head/share/man/man4/disk.4 (contents, props changed)
Modified:
head/share/man/man4/Makefile
Modified: head/share/man/man4/Makefile
==============================================================================
--- head/share/man/man4/Makefile Thu Nov 19 16:57:45 2020 (r367846)
+++ head/share/man/man4/Makefile Thu Nov 19 17:54:41 2020 (r367847)
@@ -130,6 +130,7 @@ MAN= aac.4 \
ddb.4 \
devctl.4 \
disc.4 \
+ disk.4 \
divert.4 \
${_dpms.4} \
ds1307.4 \
Added: head/share/man/man4/disk.4
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/share/man/man4/disk.4 Thu Nov 19 17:54:41 2020 (r367847)
@@ -0,0 +1,210 @@
+.\" Copyright (c) 2020 M. Warner Losh <imp at 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 at FreeBSD.org
+from text largely derived from
+.In sys/disk.h .
More information about the svn-src-head
mailing list