.IX \f4driverinfo\fP(D2DK)

NAME

driverinfo − communicate with device driver

SYNOPSIS

#include <sys/types.h>
#include <sys/buf.h>
#include <sys/dinfo.h>
#include <sys/edt.h>
int prefixdriverinfo (dev_t dev, int cmd,
int arg1, int arg2, cred_t cred_p);

ARGUMENTS

devthe dev_t for the device on which the information exchange is to take place. 

cmdthe command to be performed. 

arg1a general argument. 

arg2a general argument. 

cred_pa credential pointer for permission checking. 

DESCRIPTION

The driverinfo routine is called indirectly (through cdevsw) by the kernel to communicate with a device driver without having to open a device first (via open and ioctl). 

Drivers are free to support whatever commands they see fit (for example, firmware download or specialized hardware controller commands), and return whatever error codes seem appropriate, but drivers that implement the standardized driverinfo commands listed below must adhere to the error code returns specified by the standardized command description. 

STANDARDIZED COMMAND DXGETEDT

This command returns the extended EDT table for the devices attached to the controller for the device specified by the dev argument.  The arg1 argument is the user space virtual address of the place to return the information, and the arg2 argument is the byte count.  The extended EDT table is retrieved with two calls via driverinfo.  First, the number of extended EDT entries for the controller specified by the device argument is obtained by calling sysm88k with a buffer of one integer and a byte count of sizeof(int).  This integer (that is, the number of extended EDT structures for the argument controller) is then used to calculate how large a buffer is needed to contain the entire extended EDT table for the controller, and that buffer is then obtained.  The size of this buffer must be sizeof(int) + XEDT_count ∗ sizeof(struct xedt).  The second invocation of driverinfo with this newly obtained buffer retrieves the extended EDT table.  If the number of bytes specified by arg2 is incorrect, EINVAL is returned.  If the controller specified by the dev argument isn’t present, ENXIO is returned. 

STANDARDIZED COMMAND DDEVXEDT

This command returns the extended EDT entry for the device specified by the dev argument.  The arg1 argument is the user space virtual address of an xedt structure which will be filled in by this operation.  If the device specified by the dev argument isn’t present, ENXIO is returned. 

STANDARDIZED COMMAND DGETPERF

This command returns a struct prf_buf structure filled with a snapshot of the performance data from the device specified by the dev argument.  The arg1 argument is the user space internal address of the place to return the information.  The number of I/O queue entries to be collected is contained in the qwant field of the prf_buf structure.  The prf_buf structure is defined in sys/dinfo.h. 

STANDARDIZED COMMAND D_FRU_STATUS

This command returns the Field Replacable Unit (FRU) status for a controller and any devices attached to it the device specified by the dev argument.  The arg1 argument is the user space virtual address of a structure of type dinfo_fru_parms.  This structure contains two fields, an address, and a count.  The FRU information is retrieved with two calls via driverinfo.  First, the number of FRU entries for the controller specified by the device argument is obtained by calling sysm88k with an address of one integer and a count of sizeof(int).  This integer (that is, the number of FRU information structures for the argument controller) is then used to calculate how large a buffer is needed to contain the complete FRU information for the controller, and that buffer is then obtained.  The size of this buffer must be sizeof(int) + FRU_count ∗ sizeof(struct dinfo_fru_status).  The second invocation of driverinfo with this newly obtained buffer retrieves the FRU information.  The first FRU structure describes the controller and any FRU information structures that follow describe sub-devices attached to the controller.  The FRU status structure fields must be filled out as follows: The fru_name field must contain the correct name of the FRU.  For a "controller", this must not be the generic name of the device if the specific name can be determined via software.  The fru_present field must contain the string "yes" or "no" to indicate the physical presence of the FRU.  The fru_online field must contain the string "yes" or "no" to indicate the online status of the device.  By definition, a FRU which is not present should not be online.  The fru_location field must describe the location of the FRU.  This is done using the multi-part string convention described below.  If the geographical location of a device cannot be determined via software, then any unique attributes should be used (e.g.  controller/device number, bus address, etc.).  The fru_revision field must describe the revision information about the FRU.  This is done using the multi-part string convention described below.  This field may be empty (starting with a NULL).  The fru_self_test field must describe the self test information about the FRU.  This is done using the multi-part string convention described below.  This field must contain a minimum of one pair (see below), consisting of the the string "status" and the a string appropriately chosen from the list of "passed", "failed", or "untested".  It is acceptable to include more information as pairs following the minimum pair.  Multi-part string are composed of a separator character followed by one or more string pairs.  Each pair is composed of two strings with an intervening separator.  If the number of bytes specified by count is incorrect, EINVAL is returned.  If the controller specified by the dev argument isn’t known to the system ENXIO is returned. 

SCSI DRIVER BUS SCAN (OPTIONAL)

This command allows the scsiscan(1M) command issue requests to have SCSI buses rescan.  Any device attached to the appropriate host adapter may be used to provide the argument dev.  The arg1 argument is the user space virtual address of an dinfo_scsi_rescan structure, which is used to specify the bus scan. 

The arg field of the structure is used to specify which host adapter number to scan, with an arg value of -1 specifing all host adapters. 

The flags field of the structure is used to specify how the scan should be conducted.  The DINFO_SCSI_RESCAN_EXIST bit specifies that the devices the SCSI software believes exists should be scanned.  The DINFO_SCSI_RESCAN_DONT_EXIST bit specifies that the devices the SCSI software believes don’t exist should be scanned. 

The DINFO_SCSI_RESCAN_REMOVE bit is only valid if the DINFO_SCSI_RESCAN_EXIST bit is set and specified that devices may be removed if they no longer exist.  Support for this bit is optional. 

GENERIC ERROR RETURNS

If the command is invalid, EINVAL is returned.  Any I/O error incurred by any operation will return EIO.  If a copyin or copyout operation fails, EFAULT is returned. 

SEE ALSO

ioctl(D2DK)

DDI/DKI