24d79e9b63
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
211 lines
6.8 KiB
Groff
211 lines
6.8 KiB
Groff
.\" 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 .
|