ddmpx Device Driver Entry Point

Purpose

Allocates or deallocates a channel for a multiplexed device driver.

Syntax

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

int ddmpx ( devno,  chanp,  channame)
dev_t devno;
chan_t *chanp;
char *channame;

Parameters

Item Description
devno Specifies the major and minor device numbers.
chanp Specifies the channel ID, passed by reference.
channame Points to the path name extension for the channel to be allocated.

Description

Only multiplexed character class device drivers can provide the ddmpx routine, and every multiplexed driver must do so. The ddmpx routine cannot be provided by block device drivers even when providing raw read/write access.

A multiplexed device driver is a character class device driver that supports the assignment of channels to provide finer access control to a device or virtual subdevice. This type of device driver has the capability to decode special channel-related information appended to the end of the path name of the device's special file. This path name extension is used to identify a logical or virtual subdevice or channel.

When an open or creat subroutine call is issued to a device instance supported by a multiplexed device driver, the kernel calls the device driver's ddmpx routine to allocate a channel.

The kernel calls the ddmpx routine when a channel is to be allocated or deallocated. Upon allocation, the kernel dynamically creates g-nodes (in-core i-nodes) for channels on a multiplexed device to allow the protection attributes to differ for various channels.

To allocate a channel, the ddmpx routine is called with a channame pointer to the path name extension. The path name extension starts after the first / (slash) character that follows the special file name in the path name. The ddmpx routine should perform the following actions:

If no path name extension exists, the channame pointer points to a null character string. In this case, an available channel should be allocated and its channel ID returned through the chanp parameter.

If no error is returned from the ddmpx routine, the returned channel ID is used to determine if the channel was already allocated. If already allocated, the g-node for the associated channel has its reference count incremented. If the channel was not already allocated, a new g-node is created for the channel. In either case, the device driver's ddopen routine is called with the channel number assigned by the ddmpx routine. If a nonzero return code is returned by the ddmpx routine, the channel is assumed not to have been allocated, and the device driver's ddopen routine is not called.

If a close of a channel is requested so that the channel is no longer used (as determined by the channel's g-node reference count going to 0), the kernel calls the ddmpx routine. The ddmpx routine deallocates the channel after the ddclose routine was called to close the last use of the channel. If a nonzero return code is returned by the ddclose routine, the ddmpx routine is still called to deallocate the channel. The ddclose routine's return code is saved, to be returned to the caller. If the ddclose routine returned no error, but a nonzero return code was returned by the ddmpx routine, the channel is assumed to be deallocated, although the return code is returned to the caller.

To deallocate a channel, the ddmpx routine is called with a null channame pointer and the channel ID passed by reference in the chanp parameter. If the channel g-node reference count has gone to 0, the kernel calls the ddmpx routine to deallocate the channel after invoking the ddclose routine to close it. The ddclose routine should not itself deallocate the channel.

Execution Environment

The ddmpx routine is called in the process environment only.

Return Values

If the allocation or deallocation of a channel is successful, the ddmpx routine should return a return code of 0. If an error occurs on allocation or deallocation, this routine returns a nonzero value.

The return code should conform to the return codes described for the open and close subroutines in the POSIX 1003.1 standard, where applicable. Otherwise, the return code should be one defined in the /usr/include/sys/errno.h file.