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

NAME
     disk, disk_init, disk_attach, disk_detach, disk_destroy, disk_busy,
     disk_unbusy, 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_detach(struct disk *);

     void
     disk_destroy(struct disk *);

     void
     disk_busy(struct disk *);

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

     struct disk *
     disk_find(const char *);

     void
     disk_blocksize(struct disk *, int blocksize);

DESCRIPTION
     The NetBSD generic disk framework is designed to provide flexible, scal-
     able, 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 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_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_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 suitable values derived from the sup-
                       plied physical blocksize.  It is only necessary 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_detach(), disk_destroy,() disk_busy(), disk_unbusy(),
     and disk_blocksize().  The function disk_find() is provided as a utility
     function.

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 auto-
     configuration 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 sys-
     tem 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 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 cur-
     rently 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.  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.  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.

     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 transfered.  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,
                 bp != NULL ? bp->b_flags & B_READ : 0);

             [ . . . ]
     }

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

CODE REFERENCES
     This section describes places within the NetBSD source tree where actual
     code implementing or using the disk framework can be found.  All path-
     names are relative to /usr/src.

     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 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 and vnd drivers use the detachment capability of the
     framework.  They are located in sys/dev/ccd.c and sys/dev/vnd.c.

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

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

NetBSD 5.0.1                      May 3, 2008                     NetBSD 5.0.1

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias <christia@softlab.ntua.gr>
©1996-2014 Modified for NetBSD by Kimmo Suominen