xref: /freebsd/share/man/man4/disk.4 (revision 24d79e9b638a1fcd1b4c2568dededb6dbd66872f)

.\" 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 .