Index: head/share/man/man4/Makefile =================================================================== --- head/share/man/man4/Makefile +++ head/share/man/man4/Makefile @@ -130,6 +130,7 @@ ddb.4 \ devctl.4 \ disc.4 \ + disk.4 \ divert.4 \ ${_dpms.4} \ ds1307.4 \ Index: head/share/man/man4/disk.4 =================================================================== --- head/share/man/man4/disk.4 +++ head/share/man/man4/disk.4 @@ -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 .