config(D2)

Synopsis

   #include <sys/confmgr.h>
   #include <sys/ddi.h>

   int prefixconfig(cfg_func_t func, void idata, rm_key_t key);

Description

Arguments

func

func identifies the action to be taken. Valid subfunctions are:

CFG_ADD

Inform the driver of a new device instance to be managed, identified by key. The driver should allocate and initialize any data structures that are needed to manage the instance.

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

Tell the driver to use new hardware parameters for device instance idata. The driver must no longer access the resource manager key that was previously attached to the device instance or the associated actual device. Instead, it must obtain new parameters from the new resource manager key, key, which may or may not be the same key that was previously associated with the device instance. All subsequent accesses to resource manager information for this device instance must be through the new key.

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.

CFG_REMOVE

Tell the driver to stop managing the device instance identified by idata. The driver should not access the device or its corresponding resource manager key any more, even in this routine. Any data structures that were allocated in the CFG_ADD subfunction should be freed, unless the driver is currently open.

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.

CFG_SUSPEND

Tell the driver to suspend all activity to the device instance identified by idata, waiting first for any outstanding transactions to complete. Interrupt attachments and device memory mappings for this device instance should be freed, and no more accesses made to the device once this routine returns.

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

Tell the driver to continue operation of a device instance, identified by idata, after a CFG_SUSPEND operation. If the device being resumed is not the same actual device that was suspended, the CFG_MODIFY subfunction will already have been called. The CFG_RESUME subfunction can assume that the device and its instance data are all ready to go.

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.

CFG_VERIFY

Verify that the device identified by the resource manager key, key, is a device that can be supported by the driver. If so, the driver should return 0; otherwise, it should return ENODEV.

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.

idata

Pointer to the driver-specific device instance data, as returned by the CFG_ADD subfunction. For CFG_ADD, this argument is treated specially. Some subfunctions do not use this argument.

key

Resource manager key that selects a particular device instance. This argument is not used by some subfunctions, because the resource manager key is accessed as part of the idata value that is returned by the CFG_ADD subfunction.

Return values

Usage

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.

Context and synchronization

Hardware applicability

Version applicability

Differences between versions

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.

External dependencies

Drivers that and supply a CFG_VERIFY subfunction specify a ``Y'' in the third field of the driver's Drvmap(DSP/4dsp) file.

References

config(D2mdi), config(D2sdi), config(D2str)

``Autoconfiguration'' in HDK Technical Reference
``Hotplug devices'' in HDK Technical Reference
``Resource manager database'' in HDK Technical Reference

Examples