From owner-svn-src-head@freebsd.org Thu Nov 19 17:54:42 2020 Return-Path: Delivered-To: svn-src-head@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id A36D2470ABA; Thu, 19 Nov 2020 17:54:42 +0000 (UTC) (envelope-from imp@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4CcS4L4JKJz3C8Z; Thu, 19 Nov 2020 17:54:42 +0000 (UTC) (envelope-from imp@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 86756149; Thu, 19 Nov 2020 17:54:42 +0000 (UTC) (envelope-from imp@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id 0AJHsg0B033334; Thu, 19 Nov 2020 17:54:42 GMT (envelope-from imp@FreeBSD.org) Received: (from imp@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id 0AJHsgGB033332; Thu, 19 Nov 2020 17:54:42 GMT (envelope-from imp@FreeBSD.org) Message-Id: <202011191754.0AJHsgGB033332@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: imp set sender to imp@FreeBSD.org using -f From: Warner Losh Date: Thu, 19 Nov 2020 17:54:42 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r367847 - head/share/man/man4 X-SVN-Group: head X-SVN-Commit-Author: imp X-SVN-Commit-Paths: head/share/man/man4 X-SVN-Commit-Revision: 367847 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 19 Nov 2020 17:54:42 -0000 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 +.\" +.\" 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 .