Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

NetBSD 6.1.5 - man page for disk (netbsd section 9)

DISK(9) 			  BSD Kernel Developer's Manual 			  DISK(9)

NAME
     disk, disk_init, disk_attach, disk_begindetach, disk_detach, disk_destroy, disk_busy,
     disk_unbusy, disk_isbusy, disk_find, disk_blocksize -- generic disk framework

SYNOPSIS
     #include <sys/types.h>
     #include <sys/disklabel.h>
     #include <sys/disk.h>

     void
     disk_init(struct disk *, const char *name, const struct dkdriver *driver);

     void
     disk_attach(struct disk *);

     void
     disk_begindetach(struct disk *, int (*lastclose)(device_t), device_t self, int flags);

     void
     disk_detach(struct disk *);

     void
     disk_destroy(struct disk *);

     void
     disk_busy(struct disk *);

     void
     disk_unbusy(struct disk *, long bcount, int read);

     bool
     disk_isbusy(struct disk *);

     struct disk *
     disk_find(const char *);

     void
     disk_blocksize(struct disk *, int blocksize);

DESCRIPTION
     The NetBSD generic disk framework is designed to provide flexible, scalable, and consistent
     handling of disk state and metrics information.  The fundamental component of this framework
     is the disk structure, which is defined as follows:

     struct disk {
	     TAILQ_ENTRY(disk) dk_link;      /* link in global disklist */
	     const char      *dk_name;	     /* disk name */
	     prop_dictionary_t dk_info;      /* reference to disk-info dictionary */
	     int	     dk_bopenmask;   /* block devices open */
	     int	     dk_copenmask;   /* character devices open */
	     int	     dk_openmask;    /* composite (bopen|copen) */
	     int	     dk_state;	     /* label state   ### */
	     int	     dk_blkshift;    /* shift to convert DEV_BSIZE to blks */
	     int	     dk_byteshift;   /* shift to convert bytes to blks */

	     /*
	      * Metrics data; note that some metrics may have no meaning
	      * on certain types of disks.
	      */
	     struct io_stats *dk_stats;

	     const struct dkdriver *dk_driver;	     /* pointer to driver */

	     /*
	      * Information required to be the parent of a disk wedge.
	      */
	     kmutex_t	     dk_rawlock;     /* lock on these fields */
	     u_int	     dk_rawopens;    /* # of openes of rawvp */
	     struct vnode    *dk_rawvp;      /* vnode for the RAW_PART bdev */

	     kmutex_t	     dk_openlock;    /* lock on these and openmask */
	     u_int	     dk_nwedges;     /* # of configured wedges */
					     /* all wedges on this disk */
	     LIST_HEAD(, dkwedge_softc) dk_wedges;

	     /*
	      * Disk label information.  Storage for the in-core disk label
	      * must be dynamically allocated, otherwise the size of this
	      * structure becomes machine-dependent.
	      */
	     daddr_t	     dk_labelsector;	     /* sector containing label */
	     struct disklabel *dk_label;     /* label */
	     struct cpu_disklabel *dk_cpulabel;
     };

     The system maintains a global linked-list of all disks attached to the system.  This list,
     called disklist, may grow or shrink over time as disks are dynamically added and removed
     from the system.  Drivers which currently make use of the detachment capability of the
     framework are the ccd, dm, and vnd pseudo-device drivers.

     The following is a brief description of each function in the framework:

     disk_init()       Initialize the disk structure.

     disk_attach()     Attach a disk; allocate storage for the disklabel, set the ``attached
		       time'' timestamp, insert the disk into the disklist, and increment the
		       system disk count.

     disk_begindetach()
		       Check whether the disk is open, and if not, return 0.  If the disk is
		       open, and DETACH_FORCE is not set in flags, return EBUSY.  Otherwise, call
		       the provided lastclose routine (if not NULL) and return its exit code.

     disk_detach()     Detach a disk; free storage for the disklabel, remove the disk from the
		       disklist, and decrement the system disk count.  If the count drops below
		       zero, panic.

     disk_destroy()    Release resources used by the disk structure when it is no longer
		       required.

     disk_busy()       Increment the disk's ``busy counter''.  If this counter goes from 0 to 1,
		       set the timestamp corresponding to this transfer.

     disk_unbusy()     Decrement a disk's busy counter.  If the count drops below zero, panic.
		       Get the current time, subtract it from the disk's timestamp, and add the
		       difference to the disk's running total.	Set the disk's timestamp to the
		       current time.  If the provided byte count is greater than 0, add it to the
		       disk's running total and increment the number of transfers performed by
		       the disk.  The third argument read specifies the direction of I/O; if non-
		       zero it means reading from the disk, otherwise it means writing to the
		       disk.

     disk_isbusy()     Returns true if disk is marked as busy and false if it is not.

     disk_find()       Return a pointer to the disk structure corresponding to the name provided,
		       or NULL if the disk does not exist.

     disk_blocksize()  Initialize dk_blkshift and dk_byteshift members of struct disk with suit-
		       able values derived from the supplied physical blocksize.  It is only nec-
		       essary to call this function if the device's physical blocksize is not
		       DEV_BSIZE.

     The functions typically called by device drivers are disk_init() disk_attach(),
     disk_begindetach(), disk_detach(), disk_destroy(), disk_busy(), disk_unbusy(), and
     disk_blocksize().	The function disk_find() is provided as a utility function.

DISK IOCTLS
     The following ioctls should be implemented by disk drivers:

     DIOCGDINFO struct disklabel
	     Get disklabel.

     DIOCSDINFO struct disklabel
	     Set in-memory disklabel.

     DIOCWDINFO struct disklabel
	     Set in-memory disklabel and write on-disk disklabel.

     DIOCGPART struct partinfo
	     Get partition information.  This is used internally.

     DIOCRFORMAT struct format_op
	     Read format.

     DIOCWFORMAT struct format_op
	     Write format.

     DIOCSSTEP int
	     Set step rate.

     DIOCSRETRIES int
	     Set number of retries.

     DIOCKLABEL int
	     Specify whether to keep or drop the in-memory disklabel when the device is closed.

     DIOCWLABEL int
	     Enable or disable writing to the part of the disk that contains the label.

     DIOCSBAD struct dkbad
	     Set kernel dkbad.

     DIOCEJECT int
	     Eject removable disk.

     DIOCLOCK int
	     Lock or unlock disk pack.	For devices with removable media, locking is intended to
	     prevent the operator from removing the media.

     DIOCGDEFLABEL struct disklabel
	     Get default label.

     DIOCCLRLABEL
	     Clear disk label.

     DIOCGCACHE int
	     Get status of disk read and write caches.	The result is a bitmask containing the
	     following values:

	     DKCACHE_READ     Read cache enabled.

	     DKCACHE_WRITE    Write(back) cache enabled.

	     DKCACHE_RCHANGE  Read cache enable is changeable.

	     DKCACHE_WCHANGE  Write cache enable is changeable.

	     DKCACHE_SAVE     Cache parameters may be saved, so that they persist across reboots
			      or device detach/attach cycles.

     DIOCSCACHE int
	     Set status of disk read and write caches.	The input is a bitmask in the same format
	     as used for DIOCGCACHE.

     DIOCCACHESYNC int
	     Synchronise the disk cache.  This causes information in the disk's write cache (if
	     any) to be flushed to stable storage.  The argument specifies whether or not to
	     force a flush even if the kernel believes that there is no outstanding data.

     DIOCBSLIST struct disk_badsecinfo
	     Get bad sector list.

     DIOCBSFLUSH
	     Flush bad sector list.

     DIOCAWEDGE struct dkwedge_info
	     Add wedge.

     DIOCGWEDGEINFO struct dkwedge_info
	     Get wedge information.

     DIOCDWEDGE struct dkwedge_info
	     Delete wedge.

     DIOCLWEDGES struct dkwedge_list
	     List wedges.

     DIOCGSTRATEGY struct disk_strategy
	     Get disk buffer queue strategy.

     DIOCSSTRATEGY struct disk_strategy
	     Set disk buffer queue strategy.

     DIOCGDISKINFO struct plistref
	     Get disk-info dictionary.

USING THE FRAMEWORK
     This section includes a description on basic use of the framework and example usage of its
     functions.  Actual implementation of a device driver which uses the framework may vary.

     Each device in the system uses a ``softc'' structure which contains autoconfiguration and
     state information for that device.  In the case of disks, the softc should also contain one
     instance of the disk structure, e.g.:

     struct foo_softc {
	     device_t	     sc_dev;	     /* generic device information */
	     struct  disk    sc_dk;	     /* generic disk information */
	     [ . . . more . . . ]
     };

     In order for the system to gather metrics data about a disk, the disk must be registered
     with the system.  The disk_attach() routine performs all of the functions currently required
     to register a disk with the system including allocation of disklabel storage space, record-
     ing of the time since boot that the disk was attached, and insertion into the disklist.
     Note that since this function allocates storage space for the disklabel, it must be called
     before the disklabel is read from the media or used in any other way.  Before disk_attach()
     is called, a portions of the disk structure must be initialized with data specific to that
     disk.  For example, in the ``foo'' disk driver, the following would be performed in the
     autoconfiguration ``attach'' routine:

     void
     fooattach(device_t parent, device_t self, void *aux)
     {
	     struct foo_softc *sc = device_private(self);
	     [ . . . ]

	     /* Initialize and attach the disk structure. */
	     disk_init(&sc->sc_dk, device_xname(self), &foodkdriver);
	     disk_attach(&sc->sc_dk);

	     /* Read geometry and fill in pertinent parts of disklabel. */
	     [ . . . ]
	     disk_blocksize(&sc->sc_dk, bytes_per_sector);
     }

     The foodkdriver above is the disk's ``driver'' switch.  This switch currently includes a
     pointer to the disk's ``strategy'' routine.  This switch needs to have global scope and
     should be initialized as follows:

     void foostrategy(struct buf *);

     const struct dkdriver foodkdriver = {
	     .d_strategy = foostrategy,
     };

     Once the disk is attached, metrics may be gathered on that disk.  In order to gather metrics
     data, the driver must tell the framework when the disk starts and stops operations.  This
     functionality is provided by the disk_busy() and disk_unbusy() routines.  Because struct
     disk is part of device driver private data it needs to be guarded.  Mutual exclusion must be
     done by driver disk_busy() and disk_unbusy() are not thread safe.	The disk_busy() routine
     should be called immediately before a command to the disk is sent, e.g.:

     void
     foostart(sc)
	     struct foo_softc *sc;
     {
	     [ . . . ]

	     /* Get buffer from drive's transfer queue. */
	     [ . . . ]

	     /* Build command to send to drive. */
	     [ . . . ]

	     /* Tell the disk framework we're going busy. */
	     mutex_enter(&sc->sc_dk_mtx);
	     disk_busy(&sc->sc_dk);
	     mutex_exit(&sc->sc_dk_mtx);

	     /* Send command to the drive. */
	     [ . . . ]
     }

     When disk_busy() is called, a timestamp is taken if the disk's busy counter moves from 0 to
     1, indicating the disk has gone from an idle to non-idle state.  At the end of a transac-
     tion, the disk_unbusy() routine should be called.	This routine performs some consistency
     checks, such as ensuring that the calls to disk_busy() and disk_unbusy() are balanced.  This
     routine also performs the actual metrics calculation.  A timestamp is taken and the differ-
     ence from the timestamp taken in disk_busy() is added to the disk's total running time.  The
     disk's timestamp is then updated in case there is more than one pending transfer on the
     disk.  A byte count is also added to the disk's running total, and if greater than zero, the
     number of transfers the disk has performed is incremented.  The third argument read speci-
     fies the direction of I/O; if non-zero it means reading from the disk, otherwise it means
     writing to the disk.

     void
     foodone(xfer)
	     struct foo_xfer *xfer;
     {
	     struct foo_softc = (struct foo_softc *)xfer->xf_softc;
	     struct buf *bp = xfer->xf_buf;
	     long nbytes;
	     [ . . . ]

	     /*
	      * Get number of bytes transferred.  If there is no buf
	      * associated with the xfer, we are being called at the
	      * end of a non-I/O command.
	      */
	     if (bp == NULL)
		     nbytes = 0;
	     else
		     nbytes = bp->b_bcount - bp->b_resid;

	     [ . . . ]

	     mutex_enter(&sc->sc_dk_mtx);
	     /* Notify the disk framework that we've completed the transfer. */
	     disk_unbusy(&sc->sc_dk, nbytes,
		 bp != NULL ? bp->b_flags & B_READ : 0);
	     mutex_exit(&sc->sc_dk_mtx);

	     [ . . . ]
     }

     disk_isbusy() is used to get status of disk device it returns true if device is currently
     busy and false if it is not.  Like disk_busy() and disk_unbusy() it requires explicit lock-
     ing from user side.

CODE REFERENCES
     The disk framework itself is implemented within the file sys/kern/subr_disk.c.  Data struc-
     tures and function prototypes for the framework are located in sys/sys/disk.h.

     The NetBSD machine-independent SCSI disk and CD-ROM drivers use the disk framework.  They
     are located in sys/scsi/sd.c and sys/scsi/cd.c.

     The NetBSD ccd, dm, and vnd drivers use the detachment capability of the framework.  They
     are located in sys/dev/ccd.c, sys/dev/vnd.c, and sys/dev/dm/device-mapper.c.

SEE ALSO
     ccd(4), dm(4), vnd(4)

HISTORY
     The NetBSD generic disk framework appeared in NetBSD 1.2.

AUTHORS
     The NetBSD generic disk framework was architected and implemented by Jason R. Thorpe
     <thorpej@NetBSD.org>.

BSD					December 30, 2009				      BSD


All times are GMT -4. The time now is 01:50 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password