ddconfig Device Driver Entry Point

Purpose

Performs configuration functions for a device driver.

Syntax

#include <sys/device.h>
#include <sys/types.h>

int ddconfig ( devno,  cmd,  uiop)
dev_t devno;
int cmd;
struct uio *uiop;

Parameters

Item Description
devno Specifies the major and minor device numbers.
cmd Specifies the function to be performed by the ddconfig routine.
uiop Points to a uio structure describing the relevant data area for configuration information.

Description

The ddconfig entry point is used to configure a device driver. It can be called to do the following tasks:

The ddconfig routine is called by the device's Configure, Unconfigure, or Change method. Typically, it is called once for each device number (major and minor) to be supported. This is, however, device-dependent. The specific device method and ddconfig routine determines the number of times it is called.

The ddconfig routine can also provide additional device-specific functions relating to configuration, such as returning device vital product data (VPD). The ddconfig routine is usually invoked through the sysconfig subroutine by the device-specific Configure method.

Device drivers and their methods typically support these values for the cmd parameter:

Value Description
CFG_INIT Initializes the device driver and internal data areas. This typically involves the minor number specified by the devno parameter, for validity. The device driver's ddconfig routine also installs the device driver's entry points in the device switch table, if this was the first time called (for the specified major number). This can be accomplished by using the devswadd kernel service along with a devsw structure to add the device driver's entry points to the device switch table for the major device number supplied in the devno parameter.

The CFG_INIT command parameter should also copy the device-dependent information (found in the device-dependent structure provided by the caller) into a static or dynamically allocated save area for the specified device. This information should be used when the ddopen routine is later called.

The device-dependent structure's address and length are described in the uio structure pointed to by the uiop parameter. The uiomove kernel service can be used to copy the device-dependent structure into the device driver's data area.

When the ddopen routine is called, the device driver passes device-dependent information to the routines or other device drivers providing the device handler role in order to initialize the device. The delay in initializing the device until the ddopen call is received is useful in order to delay the use of valuable system resources (such as DMA channels and interrupt levels) until the device is actually needed.

CFG_TERM Terminates the device driver associated with the specified device number, as represented by the devno parameter.The ddconfig routine determines if any opens are outstanding on the specified devno parameter. If none are, the CFG_TERM command processing marks the device as terminated, disallowing any subsequent opens to the device. All dynamically allocated data areas associated with the specified device number should be freed.

If this termination removes the last minor number supported by the device driver from use, the devswdel kernel service should be called to remove the device driver's entry points from the device switch table for the specified devno parameter.

If opens are outstanding on the specified device, the terminate operation is rejected with an appropriate error code returned. The Unconfigure method can subsequently unload the device driver if all uses of it have been terminated.

To determine if all the uses of the device driver have been terminated, a device method can make a sysconfig subroutine call. By using the sysconfig SYS_QDVSW operation, the device method can learn whether or not the device driver has removed itself from the device switch table.

CFG_QVPD Queries device-specific vital product data (VPD).

For this function, the calling routine sets up a uio structure pointed at by the uiop parameter to the ddconfig routine. This uio structure defines an area in the caller's storage in which the ddconfig routine is to write the VPD. The uiomove kernel service can be used to provide the data copy operation.

The data area pointed at by the uiop parameter has two different purposes, depending on the cmd function. If the CFG_INIT command has been requested, the uiop structure describes the location and length of the device-dependent data structure (DDS) from which to read the information. If the CFG_QVPD command has been requested, the uiop structure describes the area in which to write vital product data information. The content and format of this information is established by the specific device methods in conjunction with the device driver.

The uiomove kernel service can be used to facilitate copying information into or out of this data area. The format of the uio structure is defined in the /usr/include/sys/uio.h file and described further in the uio structure.

Execution Environment

The ddconfig routine and its operations are called in the process environment only.

Return Values

The ddconfig routine sets the return code to 0 if no errors are detected for the operation specified. If an error is to be returned to the caller, a nonzero return code should be provided. The return code used should be one of the values defined in the /usr/include/sys/errno.h file.

If this routine was invoked by a sysconfig subroutine call, the return code is passed to its caller (typically a device method). It is passed by presenting the error code in the errno global variable and providing a -1 return code to the subroutine.