Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DISK(9)			 BSD Kernel Developer's	Manual		       DISK(9)

     disk -- kernel disk storage API

     #include <geom/geom_disk.h>

     struct disk *

     disk_create(struct	disk *disk, int	version);

     disk_gone(struct disk *disk);

     disk_destroy(struct disk *disk);

     The disk storage API permits kernel device	drivers	providing access to
     disk-like storage devices to advertise the	device to other	kernel compo-
     nents, including GEOM(4) and devfs(5).

     Each disk device is described by a	struct disk structure, which contains
     a variety of parameters for the disk device, function pointers for	vari-
     ous methods that may be performed on the device, as well as private data
     storage for the device driver.  In	addition, some fields are reserved for
     use by GEOM in managing access to the device and its statistics.

     GEOM has the ownership of struct disk, and	drivers	must allocate storage
     for it with the disk_alloc() function, fill in the	fields and call
     disk_create() when	the device is ready to service requests.  disk_gone()
     orphans all of the	providers associated with the drive, setting an	error
     condition of ENXIO	in each	one.  In addition, it prevents a re-taste on
     last close	for writing if an error	condition has been set in the
     provider.	After calling disk_destroy(), the device driver	is not allowed
     to	access the contents of struct disk anymore.

     The disk_create() function	takes a	second parameter, version, which must
     always be passed DISK_VERSION.  If	GEOM detects that the driver is	com-
     piled against an unsupported version, it will ignore the device and print
     a warning on the console.

   Descriptive Fields
     The following fields identify the disk device described by	the structure
     instance, and must	be filled in prior to submitting the structure to
     disk_create() and may not be subsequently changed:

     u_int d_flags
	     Optional flags indicating to the storage framework	what optional
	     features or descriptions the storage device driver	supports.
	     Currently supported flags are DISKFLAG_NEEDSGIANT (maintained by
	     device driver), DISKFLAG_OPEN (maintained by storage framework),
	     DISKFLAG_CANDELETE	(maintained by device driver), and
	     DISKFLAG_CANFLUSHCACHE (maintained	by device driver).

     const char	* d_name
	     Holds the name of the storage device class, e.g., "ahd".  This
	     value typically uniquely identifies a particular driver device,
	     and must not conflict with	devices	serviced by other device driv-

     u_int d_unit
	     Holds the instance	of the storage device class, e.g., "4".	 This
	     namespace is managed by the device	driver,	and assignment of unit
	     numbers might be a	property of probe order, or in some cases
	     topology.	Together, the d_name and d_unit	values will uniquely
	     identify a	disk storage device.

   Disk	Device Methods
     The following fields identify various disk	device methods,	if imple-

     disk_open_t * d_open
	     Optional: invoked when the	disk device is opened.	If no method
	     is	provided, open will always succeed.

     disk_close_t * d_close
	     Optional: invoked when the	disk device is closed.	Although an
	     error code	may be returned, the call should always	terminate any
	     state setup by the	corresponding open method call.

     disk_strategy_t * d_strategy
	     Mandatory:	invoked	when a new struct bio is to be initiated on
	     the disk device.

     disk_ioctl_t * d_ioctl
	     Optional: invoked when an I/O control operation is	initiated on
	     the disk device.  Please note that	for security reasons these op-
	     erations should not be able to affect other devices than the one
	     on	which they are performed.

     dumper_t *	d_dump
	     Optional: if configured with dumpon(8), this function is invoked
	     from a very restricted system state after a kernel	panic to
	     record a copy of the system RAM to	the disk.

   Mandatory Media Properties
     The following fields identify the size and	granularity of the disk	de-
     vice.  These fields must stay stable from return of the drivers open
     method until the close method is called, but it is	perfectly legal	to
     modify them in the	open method before returning.

     u_int d_sectorsize
	     The sector	size of	the disk device	in bytes.

     off_t d_mediasize
	     The size of the disk device in bytes.

     u_int d_maxsize
	     The maximum supported size	in bytes of an I/O request.  Requests
	     larger than this size will	be chopped up by GEOM.

   Optional Media Properties
     These optional fields can provide extra information about the disk	de-
     vice.  Do not initialize these fields if the field/concept	does not ap-
     ply.  These fields	must stay stable from return of	the drivers open
     method until the close method is called, but it is	perfectly legal	to
     modify them in the	open method before returning.

     u_int d_fwsectors,	u_int d_fwheads
	     The number	of sectors and heads advertised	on the disk device by
	     the firmware or BIOS.  These values are almost universally	bogus,
	     but on some architectures necessary for the correct calculation
	     of	disk partitioning.

     u_int d_stripeoffset, u_int d_stripesize
	     These two fields can be used to describe the width	and location
	     of	natural	performance boundaries for most	disk technologies.
	     Please see	src/sys/geom/notes for details.

     char d_ident[DISK_IDENT_SIZE]
	     This field	can and	should be used to store	disk's serial number.

   Driver Private Data
     This field	may be used by the device driver to store a pointer to private
     data to implement the disk	service.

     void * d_drv1
	     Private data pointer.  Typically used to store a pointer to the
	     drivers softc structure for this disk device.

     GEOM(4), devfs(5)

     This manual page was written by Robert Watson.

BSD			       February	18, 2004			   BSD


Want to link to this manual page? Use this URL:

home | help