SVR5 and SCO OpenServer

open(D2str)

open -- gain access to a device

Syntax

DDI 8 and later

See open(D2) for DDI syntax, arguments, return values, and basic usage information. In DDI 8, the syntax of the open entry point routine is the same for STREAMS and non-STREAMS drivers.

DDI 7 and earlier

   int prefixopen(queue_t *q, dev_t *devp, int oflag,
                  int sflag, cred_t *crp);

ODDI

   int prefixopen(queue_t *q, dev_t *devp, int oflag, int sflag;

Description

The STREAMS module open routine is called by the kernel during an I_PUSH ioctl or an autopush-style open (see autopush). It can also be called from another (layered) driver.

See open(D2mdi) for MDI specific usage information.

Arguments

The meaning of the arguments for ODDI and DDI 7 and earlier is:

q

Pointer to the queue used to reference the read side of the driver.

devp

Pointer to a device number. For modules, devp always points to the device number associated with the driver at the end (tail) of the stream.

oflag

Open flags as documented on the open(D2) and open(D2oddi) manual pages. Note that FAPPEND, FCREAT, and FTRUNC have no meaning to a STREAMS device. For STREAMS modules, oflag is always set to 0 (zero).

sflag

STREAMS flag. The values are mutually exclusive:

CLONEOPEN: Indicates a clone open (see below.) If the driver supports cloning, it must assign and return a device number of an unused device by changing the value of the device number to which devp points. This eliminates the need for user processes to poll many minor devices when looking for an unused one. The open( ) routine must assign and return a minor number.
MODOPEN: Indicates that an open routine is being called for a module, not a driver. This is useful in detecting configuration errors and in determining how the driver is being used, since STREAMS drivers can also be configured as STREAMS modules.
0: Indicates a driver is being opened directly, without cloning.

crp

Pointer to the user credential structure (DDI only).

Return values

DDI 8 and later: See open(D2) for return values.
DDI 7 and earlier
ODDI

Usage

This entry point is required in all drivers and STREAMS modules.

The open routine may 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
change the channel if this is a clone open
enable put and service procedures for multithreaded drivers

The open routine should verify that the minor portion of the device number (pre-DDI 8 and ODDI) or channel (DDI 8) is valid, that the type of access requested by oflag is appropriate for the device, and, for DDI drivers, check permissions using the user credentials pointed to by crp (see drv_priv(D3)).

Support of cloning is optional and is most often used by pseudo-drivers rather than hardware drivers. Cloning is the process of the driver selecting an unused device for the user. It eliminates the need to poll many devices when looking for an unused one. In DDI 8, the driver can achieve a clone effect by storing a channel handle, returned from the drv_open(D3) function, in the *clone_chanp argument and returning ECLONE. This causes the kernel to open the driver and channel indicated by the channel handle and use it in place of the initial driver channel for this open. If ECLONE is not returned, the *clone_chan argument is ignored.

$maxchan value set in the driver's Node(DSP/4dsp) file and the drv_maxchan member of the drvinfo(D4) structure determines the number of device nodes needed per instance of a device. Drivers that use open redirection should create one channel for the initial open plus one for each clone channel.

For STREAMS drivers and modules, the open routine is called with interrupts blocked from all STREAMS devices. If the driver sets stream head options by sending an M_SETOPTS message upstream from the open routine, then the changes are guaranteed to take effect when the system call completes.

For STREAMS drivers and modules, for a given device number (queue), only one instance of the open( ) routine can be running at any given time. However, multiple opens on any two different device numbers (queues) can be running concurrently. It is the responsibility of the driver or module to synchronize access to its private data structures in this case. For clone opens, multiple clone opens can run concurrently, and it is the driver's responsibility to synchronize access to its private data structures, as well as allocation and deallocation of device numbers.

Synchronization constraints

The open routine has user context and can sleep. However, STREAMS drivers and modules must sleep such that signals do not cause the sleep to longjump (see sleep(D3)).

For STREAMS drivers, all calls to the open( ) and close( ) entry point routines are mutually serialized, even for multithreaded drivers.

Cloning

Cloning is the process of the driver selecting an unused device for the user. It eliminates the need to poll many devices when looking for an unused one.

In ODDI and DDI versions prior to 8, STREAMS drivers implement cloning behavior by changing the device number pointed to by devp. 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. Using this method of cloning, a STREAMS driver never sees the sflag argument set to CLONEOPEN.

Another method of performing clone opens (again, only for ODDI and DDI versions prior to 8) does use the CLONEOPEN flag. In this method, STREAMS drivers take advantage of a special driver known as the ``clone driver''. This frees the driver from having to reserve special minors for the clone entry points. Here, the device node is actually that of the clone driver (the major number is the major number from the clone driver and the minor number is the major number from the real driver.) When the clone driver is opened, it calls the real driver open routine with sflag set to CLONEOPEN.

In DDI 8, cloning (or ``open redirection'') works differently than in previous versions. There is no longer a CLONEOPEN flag or even an sflag argument to open(D2). DDI 8 drivers cannot use the clone driver; they are responsible for performing their own open redirection. A DDI 8 driver's open entry point routine checks if a particular channel number (the ``clone channel'') was requested. Each driver selects its own clone channel number or numbers. See the open(D2) manual page and the ``Clone device'' in HDK Technical Reference article for details about how to implement open redirection.

Backward compatibility

The MODOPEN flag is not used for DDI 8 STREAMS modules. In DDI 8, a STREAMS module is defined by setting the D_MOD flag in the drv_flags member of the drvinfo(D4) structure. If a kernel module wants to act as both a STREAMS module and a STREAMS driver, it must call drv_attach(D3) from its _load(D2str) routine twice; once with D_MOD set, and once without.

The unit number information that is extracted from the minor number in ODDI and pre-DDI 8 drivers is available in the idata pointer for DDI 8 and later drivers. The operating mode that was extracted from the minor number can be extracted from the channel number.

References

close(D2str), drv_attach(D3), drv_priv(D3), drvinfo(D4), errnos(D5), open(D2), open(D2mdi), qprocson(D3str), queue(D4str)

``Clone device'' in HDK Technical Reference