disk_init man page on OpenBSD

Man page or keyword search:  
man Server   11362 pages
apropos Keyword Search (all sections)
Output format
OpenBSD logo
[printable version]

DISK(9)			     OpenBSD Kernel Manual		       DISK(9)

NAME
     disk - generic disk framework

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

     void
     disk_init(void);

     void
     disk_attach(struct disk *);

     void
     disk_detach(struct disk *);

     void
     disk_busy(struct disk *);

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

DESCRIPTION
     The OpenBSD 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 */
	     struct rwlock   dk_lock;	     /* disk lock */
	     struct mutex    dk_mtx;	     /* busy/unbusy mtx */
	     char	     *dk_name;	     /* disk name */
	     struct device   *dk_device;     /* disk device structure. */
	     dev_t	     dk_devno;	     /* disk device number. */
	     int	     dk_flags;	     /* disk flags */
     #define DKF_CONSTRUCTED  0x0001
     #define DKF_OPENED	      0x0002
     #define DKF_NOLABELREAD  0x0004

	     /*
	      * Metrics data; note that some metrics may have no meaning
	      * on certain types of disks.
	      */
	     int       dk_busy;	     /* busy counter */
	     u_int64_t dk_rxfer;     /* total number of read transfers */
	     u_int64_t dk_wxfer;     /* total number of write transfers */
	     u_int64_t dk_seek;	     /* total independent seek operations */
	     u_int64_t dk_rbytes;    /* total bytes read */
	     u_int64_t dk_wbytes;    /* total bytes written */
	     struct timeval  dk_attachtime;  /* time disk was attached */
	     struct timeval  dk_timestamp; /*time of first busy or any unbusy*/
	     struct timeval  dk_time;	     /* total time spent busy */

	     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 */

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

     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(4) and vnd(4) pseudo-device drivers.

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

     disk_init()    Initialize the disklist and other data structures used by
		    the framework.  Called by main() before autoconfiguration.

     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_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_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, print a warning message.  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.

     The functions typically called by device drivers are disk_attach(),
     disk_detach(), disk_busy() and disk_unbusy().

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 utilizes the framework may vary.

     A special routine, disk_init(), is provided to perform basic
     initialization of data structures used by the framework.  It is called
     exactly once by the system, in main(), before device autoconfiguration.

     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 {
	     struct  device *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, recording 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 portion 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(parent, self, aux)
	     struct device *parent, *self;
	     void *aux;
     {
	     struct foo_softc *sc = (struct foo_softc *)self;
	     [ . . . ]

	     /* Initialize and attach the disk structure. */
	     sc->sc_dk.dk_driver = &foodkdriver;
	     sc->sc_dk.dk_name = sc->sc_dev.dv_xname;
	     disk_attach(&sc->sc_dk);

	     /* Read geometry and fill in pertinent parts of disklabel. */
	     [ . . . ]
     }

     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 *);
     struct  dkdriver foodkdriver = { 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.  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. */
	     disk_busy(&sc->sc_dk);

	     /* 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.  Note that disk_busy() must be called at splbio().	 At
     the end of a transaction, 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
     difference 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.

     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;

	     [ . . . ]

	     /* Notify the disk framework that we've completed the transfer. */
	     disk_unbusy(&sc->sc_dk, nbytes);

	     [ . . . ]
     }

     Like disk_busy(), disk_unbusy() must be called at splbio().

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

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

     The OpenBSD ccd(4), raid(4) and vnd(4) drivers utilize the detachment
     capability of the framework.  They are located in sys/dev/ccd.c,
     sys/dev/raidframe/, and sys/dev/vnd.c.

SEE ALSO
     ccd(4), raid(4), vnd(4), spl(9)

HISTORY
     The OpenBSD generic disk framework first appeared in NetBSD 1.2.

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

OpenBSD 4.9		       November 17, 2010		   OpenBSD 4.9
[top]

List of man pages available for OpenBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net