|
|
#include <sys/confmgr.h> #include <sys/ddi.h>int prefixconfig(cfg_func_t func, void idata, rm_key_t key);
For this subfunction, *idata is an output argument rather than an input argument. The driver must allocate a driver-specific device instance data structure and set (void )idata equal to a pointer to this data structure (or to some other value it can subsequently use to identify the device instance and locate the corresponding instance data).
The idata value output by the CFG_ADD subfunction will be passed back to the driver in all subsequent entry points that are related to this device instance. Logically, this is equivalent to passing the resource manager key to every entry point, but allows the driver to access cached information without incurring the cost of accessing the resource manager database on every operation. See ``Device instance'' in HDK Technical Reference.
CFG_MODIFY may be used either to replace one piece of hardware with another or to correct a hardware parameter value. The driver is responsible for resetting the new hardware to a known state and programming it with any options or parameters (such as MAC address for a network adapter card) that were previously programmed into the original device instance.
CFG_MODIFY is called only for a device instance that is currently suspended with the CFG_SUSPEND subfunction. The new key and its associated device are guaranteed not to be currently associated with any other device instance. CFG_MODIFY is not required, but if no CFG_MODIFY subfunction is coded, CFG_RESUME must do the equivalent checks of the key parameter.
Any I/O requests that were pending at the time of the CFG_REMOVE call, as well as any new I/O requests that arrive subsequently for this device instance, should be failed.
CFG_REMOVE is called only for a device instance that is currently attached (that is, CFG_ADD has been called without a matching CFG_REMOVE call). The device instance may or may not be currently suspended and/or open. CFG_REMOVE is called in response to instructions from the Hot Plug Manager, by the _unload(D2) entry point routine when the driver is unloaded, or in the undesireable case that the device is just removed from a running system without first being suspended and removed through the Hot Plug Manager.
For this subfunction, key is undefined and should not be referenced.
Any new I/O requests submitted to the driver after the CFG_SUSPEND call should be queued by the driver and held until a subsequent CFG_REMOVE or CFG_RESUME call is issued. Requests already queued in the driver, but not yet sent to the device, may either be completed or held. Any requests sent to the device that do not complete in a reasonable amount of time should be aborted and failed.
If the device has caches, they should be flushed.
CFG_SUSPEND is called when the driver is explicitly suspended and during system shutdown. It is called only for a device instance that is currently attached (that is, CFG_ADD has been called without a matching CFG_REMOVE call) and is not already suspended.
For this subfunction, key is valid and matches the key that was previously passed in by the CFG_ADD or CFG_MODIFY subfunction for this instance.
CFG_RESUME is called only for a device instance that is currently suspended with the CFG_SUSPEND subfunction. If the driver does not code a CFG_MODIFY subfunction, CFG_RESUME must check whether the key is the same or different than the key used when CFG_SUSPEND was called.
For this subfunction, key is valid and matches the key that was previously passed in by the CFG_ADD or CFG_MODIFY subfunction for this instance.
When CFG_VERIFY is called, there may or may not be a corresponding attached device instance and it may or may not currently be suspended.
For this subfunction, idata is undefined and should not be referenced.
Note that, unlike the earlier _verify(D2) entry point routine, CFG_VERIFY is called after the driver is loaded with the _load(D2) entry point routine, like all other config( ) subfunctions.
All hardware drivers must support the CFG_ADD subfunction. Other subfunctions are optional, and provide increased functionality if supported. All drivers for hot plug devices must support the CFG_ADD, CFG_MODIFY, CFG_REMOVE, CFG_SUSPEND, and CFG_RESUME subfunctions and include the D_HOT flag in their drvinfo(D4) structures.
The CFG_MODIFY subfunction is not useful without the CFG_SUSPEND and CFG_RESUME subfunctions.
The CFG_SUSPEND and CFG_REMOVE subfunctions must both call the cm_intr_detach(D3) function to detach interrupts. The CFG_REMOVE subfunction should detach interrupts conditionally, only if the driver is not already suspended. The CFG_SUSPEND and CFG_REMOVE subfunctions should also cancel any pending itimeout(D3) and bufcall(D3str) calls for the device instance.
The CFG_VERIFY subfunction is provided primarily for drivers that control ISA devices. Using this subfunction allows the user to try different configuration parameters and get instant feedback rather than having to rebuild the entire kernel to see if the configuration parameters they have selected are valid.
The CFG_VERIFY subfunction may be called to test uncertain hardware parameters, it should be written to perform correctly if the current parameter values are invalid. 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 example, a driver could read all of its readable I/O addresses first. If any are missing or contain unexpected values, the configuration should fail. Only after it passes all read tests should the driver perform any tests that require writing to I/O addresses.
The CFG_VERIFY subfunction should not add new parameters to the resource manager database or change the value of exising parameters. The config(D2mdi) manual page includes a code sample for the CFG_VERIFY subfunction for an MDI network adapter.
In the current implementation, all calls to config( ) subfunctions are single-threaded by the kernel, but drivers should be coded so that they can handle concurrent config( ) calls, especially for the CFG_ADD subfunction. However, because each CFG_ADD is for a separate instance and most drivers do not need a global state, this does not affect how most drivers are coded. Nothing else can happen on the new driver instance until the CFG_ADD subfunction completes execution, so access to the instance data is in fact single-threaded during the CFG_ADD execution.
cm_getnbrd(D3) and cm_getbrdkey(D3) are used in earlier versions during the start(D2) and _load(D2) entry point routines to obtain instance information, corresponding to the CFG_ADD subfunction. All other subfunctions provide functionality that is new in DDI 8.
d_config
member of their
drvops(D4)
structure.
Drivers that and supply a CFG_VERIFY subfunction specify a ``Y'' in the third field of the driver's Drvmap(DSP/4dsp) file.
config(D2mdi), config(D2sdi), config(D2str)
``Autoconfiguration'' in HDK Technical Reference
``Hotplug devices'' in HDK Technical Reference
``Resource manager database'' in HDK Technical Reference