ddopen Device Driver Entry Point

Purpose

Prepares a device for reading, writing, or control functions.

Syntax

#include <sys/device.h>
  
int ddopen (devno, devflag, chan,  ext)
dev_t  devno;
ulong  devflag;
chan_t  chan;
int ext;

Parameters

Item Description
devno Indicates major and minor device numbers.
devflag Specifies open file control flags.
chan Specifies the channel number.
ext Specifies the extension parameter.

Description

The kernel calls the ddopen routine of a device driver when a program issues an open or creat subroutine call. It can also be called when a system call, kernel process, or other device driver uses the fp_opendev or fp_open kernel service to use the device.

The ddopen routine must first ensure exclusive access to the device, if necessary. Many character devices, such as printers and plotters, should be opened by only one process at a time. The ddopen routine can enforce this by maintaining a static flag variable, which is set to 1 if the device is open and 0 if not.

Each time the ddopen routine is called, it checks the value of the flag. If the value is other than 0, the ddopen routine returns with a return code of EBUSY to indicate that the device is already open. Otherwise, the ddopen routine sets the flag and returns normally. The ddclose entry point later clears the flag when the device is closed.

Since most block devices can be used by several processes at once, a block driver should not try to enforce opening by a single user.

The ddopen routine must initialize the device if this is the first open that has occurred. Initialization involves the following steps:

  1. The ddopen routine should allocate the required system resources to the device (such as DMA channels, interrupt levels, and priorities). It should, if necessary, register its device interrupt handler for the interrupt level required to support the target device. (The i_init and d_init kernel services are available for initializing these resources.)
  2. If this device driver is providing the head role for a device and another device driver is providing the handler role, the ddopen routine should use the fp_opendev kernel service to open the device handler.
    Note: The fp_opendev kernel service requires a devno parameter to identify which device handler to open. This devno value, taken from the appropriate device dependent structure (DDS), should have been stored in a special save area when this device driver's ddconfig routine was called.

Flags Defined for the devflag Parameter

The devflag parameter has the following flags, as defined in the /usr/include/sys/device.h file:

Item Description
DKERNEL Entry point called by kernel routine using the fp_opendev or fp_open kernel service.
DREAD Open for reading.
DWRITE Open for writing.
DAPPEND Open for appending.
DNDELAY Device open in nonblocking mode.

Execution Environment

The ddopen routine is executed only in the process environment. It should provide the required serialization of its data structures by using the locking kernel services in conjunction with a private lock word defined in the driver.

Return Values

The ddopen entry point can indicate an error condition to the user-mode application program by returning a nonzero return code. Returning a nonzero return code causes the open or creat subroutines to return a value of -1 and makes the return code available to the user-mode application in the errno global variable. The return code used should be one of the values defined in the /usr/include/errno.h file.

If a nonzero return code is returned by the ddopen routine, the open request is considered to have failed. No access to the device instance is available to the caller as a result. In addition, for nonmultiplexed drivers, if the failed open was the first open of the device instance, the kernel calls the driver's ddclose entry point to allow resources and device driver state to be cleaned up. If the driver was multiplexed, the kernel does not call the ddclose entry point on an open failure.

When applicable, the return values defined in the POSIX 1003.1 standard for the open subroutine should be used.

Related Information

The ddclose device driver entry point, ddconfig device driver entry point.

The fp_open kernel service, fp_opendev kernel service, i_enable kernel service, i_init kernel service.

The close subroutine, creat subroutine, open subroutine.

Device Driver Kernel Extension Overview in AIX® Version 7.1 Kernel Extensions and Device Support Programming Concepts.

Programming in the Kernel Environment Overview in AIX Version 7.1 Kernel Extensions and Device Support Programming Concepts.