SVR5

_verify(D2)

_verify -- verify that driver supports a particular device

Synopsis (Not in current DDI version)

   #include <sys/confmgr.h>
   #include <sys/ddi.h>
   
   int prefix_verify(rm_key_t key);

Description

The optional _verify( ) entry point routine can be invoked by the user when running dcu to check whether a specific set of configuration parameters are correct for a specific board.

The driver writer may also specify that the _verify( ) routine should be invoked automatically by the DCU to verify configuration parameters before DCU does its board and driver mapping. To implement this, Include a V in the ``verify'' field of the drivers Drvmap(DSP/4dsp) file. If a V appears in the ``verify'' field, the board/driver mapping is done only when the _verify( ) routine returns 0. The V is not intended for every driver and its use should be limited to very special cases. The following example illustrates why some drivers may need to use the V flag.

The Adaptec 1740 SCSI board can operate in either of two modes, standard or enhanced. A different driver is needed depending on the mode of the board. DCU does its board/driver mapping based on the board's id. Since this board has a single id, it is impossible for DCU to assign the correct driver to this board without knowing the mode of the board. By supplying _verify( ) routines and specifying V in the ``verify'' field of the Drvmap files, DCU will invoke each _verify( ) routine and correctly assign a driver based on the return values.

Not all drivers require a _verify( ) routine. Support for _verify( ) routines is provided primarily for drivers that control ISA devices. This enables the user to try different configuration parameters and get instant feedback from the DCU, and so determine the correct configuration parameters for a board without rebuilding the kernel.

Beyond support for ISA configuration and other ``special cases'', there are no other reasons to provide verify routines for drivers. Drivers that only support EISA, MCA, or PCI cards do not usually need a _verify( ) routine except in special cases, such as PCI drivers for devices that use the same ASIC. In this case, the _verify( ) routine needs to call the cm_getval(D3) function to query the CM_BRDID parameter documented on the cm_params(D5) manual page. It must then verify that the driver actually supports the adapter that is represented by the resource manager entry by obtaining the I/O or memory address of the adapter and verifying that the driver functions with this adapter. This verification may include reading a signature port that uniquely identifies the adapter, reading the PCI subsystem ID and subsystem vendor ID (see pci(D5)), or other operations that uniquely identify the adapter. Avoid writing to the adapter during the process.

Arguments

key: resource manager key used to refer to device instance

Return values

The _verify( ) routine should return 0 if the configuration parameters are correct and the driver can support the board; otherwise it should return ENODEV.

Usage

This routine is optional and is only valid for loadable autoconfigurable drivers. It is called instead of _load(D2) and _unload(D2).

The _verify( ) routine is called with a Resource Manager key that the driver uses to retrieve hardware parameters using the configuration manager interfaces. For SDI drivers, the _verify routine should call sdi_hba_getconf(D3sdi) to get the hardware parameters for a particular board (this differs from using sdi_hba_autoconf(D3sdi) which will retrieve the hardware parameters for all boards supported by the driver).

Since the _verify routine is sometimes called to test uncertain hardware parameters (for instance, to check user-supplied hardware parameters), it is important that _verify routines do their checking very carefully. Thus, it is best to not write to any I/O address unless absolutely necessary and only after all other possible read checks have been performed. For instance, a driver could read all of its readable I/O addresses first. If any are missing or contain unexpected values, it should fail. Then, it should perform any necessary tests that require writing to I/O addresses.

The _verify routine should not add new parameters to the Resource Manager database or change the value of existing parameters.

Context and synchronization

Blockable context. The driver can block but cannot do operations such as copyout(D3) that require access to the requesting process's address space.

Hardware applicability

All

Version applicability

ddi: 6, 6mp, 7, 7mp, 7.1, 7.1mp

Differences between versions

Starting with DDI version 8, _verify( ) is replaced by the CFG_VERIFY subfunction of the config(D2) entry point routine.

External dependencies

Loadable drivers that support autoconfiguration and supply a _verify( ) routine must specify a ``Y'' in the third field of the driver's Drvmap(DSP/4dsp) file.

References

dcu, cm_getval(D3), Drvmap, cm_params(D5), errnos(D5)

_verify(D2mdi)

``ISA bus autoconfiguration'' in HDK Technical Reference