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, 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 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 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 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 locking from user side.