SVR5

open(D2)

open -- gain access to a device

Synopsis

   #include <sys/types.h>
   #include <sys/file.h>
   #include <sys/errno.h>
   #include <sys/open.h>
   #include <sys/cred.h>
   #include <sys/stream.h>
   #include <sys/ddi.h>
   
   int prefixopen(void *idata, channel_t *channelp,
                int oflags, cred_t *crp, queue_t *q);

See ``Differences between versions''

Description

The driver's open( ) entry point routine is called to prepare a device for further access. It is called by the core kernel during an open or a mount call to the device special file. It can also be called from another (layered) driver. No other driver entry point routines that take a channel number argument will be called until the channel has been opened by a call to the open( ) routine.

NOTE: Starting with DDI version 8, the syntax of the open( ) entry point routine is the same for STREAMS and non-STREAMS drivers.

Arguments

idata

For hardware drivers, pointer to the device-specific instance as returned by the CFG_ADD subfunction of the config(D2) entry point routine. For software-only drivers, idata is undefined and should not be referenced. See ``Device instance'' in HDK Technical Reference.

channelp

Pointer to the channel number, used to select subcomponents and/or operating modes of this device instance. This is set to the desired channel on entry; the driver may change it to redirect the open( ) to another channel. See ``Channel number'' in HDK Technical Reference.

For STREAMS modules, channelp is undefined and should not be referenced.

oflags

Open mode flags. The following flag settings should be checked by the driver and may appear in any combination:

FREAD: Open the device for reading.
FWRITE: Open the device for writing.
FNONBLOCK: Do not block waiting for potentially long-term conditions (such as carrier detect).
FEXCL: Interpreted in a driver-dependent manner. Some drivers interpret this flag to mean "open the device with exclusive access;" in other words, fail all other attempts to open the device until it is closed.

crp

Pointer to the user credential structure.

q

Pointer to the read-side STREAMS queue for the device being opened. For non-STREAMS drivers, q is undefined and should not be referenced.

Return values

The open( ) routine should return 0 for success, or the appropriate error number from those listed on the errnos(D5) manual page.

Usage

This entry point is required for all drivers. Additional usage information for specific driver types is provided on the open(D2str), open(D2mdi), and open(D2sdi) manual pages. Note that SDI HBA drivers use a different form of this routine.

The open routine can perform any of the following general functions, depending on the type of device and the service provided:

enable device interrupts
allocate buffers or other resources needed to use the device
lock an unsharable device
notify the device of the open
redirect the open to another channel
enable put and service procedures for multithreaded STREAMS drivers

The open routine should verify that the type of access requested by oflags is appropriate for the device, and, if required, check for required privilege using the user credentials pointed to by crp; see drv_priv(D3).

Open redirection (cloning)

Some drivers may choose to implement open redirection. This allows the driver to substitute a different channel number (within the same driver instance) for the originally requested channel. Typically, this is used to provide a ``clone'' effect, where each open automatically returns a new channel, but it could also be used to provide a special channel that picks one of the ``real'' channels based on some criteria.

To implement clone behavior in a driver, designate a particular channel number to be the clone channel. When this channel is opened, the driver searches its list of open channels; the first one that is not already open becomes the target. The driver changes channelp to the new target channel number and proceeds to open that channel.

If the driver returns successfully with *channelp set to a new value, the new channel is considered to have been opened; this does not result in another open(D2) call. The original channel has not been opened and will not receive a subsequent close( ) unless it was previously opened by another call.

The $maxchan field of the Node(DSP/4dsp) file and the drv_maxchan member of the drvinfo(D4) file determine the number of channels that are allocated in the device table for this driver. Drivers that use open redirection should create one channel for the initial open plus one for each clone channel. You should allocate enough channels to support the maximum number of simultaneous open redirection operations that you anticipate, but remember that each additional channel consumes a device number from the 32-bit address space, so randomly picking artificially high numbers is not advised. The driver should be coded to handle an open redirection request that is issued when no clone devices are available. The driver can either fail the I/O operation and return an error with the cmn_err(D3) function, or it can wait for a channel to be available.

Context and synchronization

Blockable context. The driver can block but cannot do operations such as copyout(D3) that require access to the requesting process's address space.

If the FNONBLOCK flag is set in oflags, the driver must not wait for long-term conditions to change in order to complete this operation. It should, however, block for system resource allocations such as memory allocations if necessary.

Hardware applicability

All

Version applicability

ddi: 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp, 8, 8mp

Differences between versions

In DDI versions prior to version 8, the syntax of the open( ) routine for non-STREAMS drivers is:

   int prefixopen(dev_t *devp, int oflags, int otyp, cred_t *crp);

devp is a pointer to a device number. otyp is a parameter supplied so that the driver can determine how many times a device was opened and for what reasons. Valid values for otyp are listed below. These values are mutually exclusive:

OTYP_BLK: Open occurred through block interface for the device.
OTYP_CHR: Open occurred through the raw/character interface for the device.
OTYP_LYR: Open a layered device. This flag is used when one driver calls another driver's open routine.

In DDI versions prior to version 8, drivers implement open redirection by changing the device number pointed to by devp. The driver may either recognize a particular minor number as the ``clone'' minor, or if it is a STREAMS driver, it may depend on the STREAMS clone driver, and then check for the CLONEOPEN styp value. A driver may designate certain minor devices as special clone entry points into the driver. When these are opened, the driver searches for an unused device and returns the new device number by changing the value of the device number to which devp points. Both the major device number and the minor device number can be changed, although usually just the minor number is changed. The major number is only changed when the clone controls more than one device.

In DDI versions prior to version 8, the driver must treat an FNDELAY flag in oflags the same as the FNONBLOCK flag.

In DDI versions prior to version 8, open( ) is a named entry point for non-STREAMS drivers and must be defined as a global symbol.

Some earlier releases of the documentation claimed that this entry point had user context, but this was not true in all cases.

External dependencies

For DDI 8 and later versions, drivers must declare this entry point routine in the d_open member of their drvops(D4) structure.

Named entry point routines must be declared in the driver's Master(DSP/4dsp) file. The declaration for this entry point is $entry open. This applies only to non-STREAMS drivers that use DDI versions prior to version 8.

SDI HBA drivers that support passthrough operations use a different form of this routine, which is declared in the driver's hba_info(D4sdi) structure. See open(D2sdi).

References

close(D2), drv_priv(D3), errnos(D5), open(D2mdi), open(D2sdi), open(D2str).

Examples

See ``DDI: 8 sample driver'' in HDK code samples