te
Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
ldi_open_by_dev, ldi_open_by_name, ldi_open_by_devid, ldi_close - open and close devices

#include <sys/sunldi.h>

int ldi_open_by_dev(dev_t *devp, int otyp, int flag, cred_t *cr,
 ldi_handle_t *lhp, ldi_ident_t li);

int ldi_open_by_name(char *pathname, int flag, cred_t *cr,
 ldi_handle_t *lhp, ldi_ident_t li);

int ldi_open_by_devid(ddi_devid_t devid, char *minor_name, int flag,
 cred_t *cr, ldi_handle_t *lhp, ldi_ident_t li);

int ldi_close(ldi_handle_t lh, int flag, cred_t *cr);

lh lhp li cr devp pathname devid minor_name otyp flag The ldi_open_by_dev(), ldi_open_by_name() and ldi_open_by_devid() functions allow a caller to open a block, character, or streams device. Upon a successful open, a layered handle to the device is returned via the layered handle pointed to by lhp. The ldi identifier passed to these functions is previously allocated with ldi_ident_from_stream(9F), ldi_ident_from_dev(9F), and ldi_ident_from_dip(9F).

The ldi_open_by_dev() function opens a device specified by the dev_t pointed to by devp. Upon successful open, the caller should check the value of the dev_t to see if it has changed. (Cloning devices will change this value during opens.) When opening a streams device, otyp must be OTYP_CHR.

The ldi_open_by_devid() function opens a device by devid. The caller must specify the minor node name to open.

The ldi_open_by_name() function opens a device by pathname. Pathname is a null terminated string in the kernel address space. Pathname must be an absolute path, meaning that it must begin with '/'. The format of the pathname supplied to this function is either a /devices path or any other filesystem path to a device node. Opens utilizing /devices paths are supported before root is mounted. Opens utilizing other filesystem paths to device nodes are supported only if root is already mounted.

The ldi_close() function closes a layered handle that was obtained with either ldi_open_by_dev(), ldi_open_by_name(), or ldi_open_by_devid(). After ldi_close() returns the layered handle, the lh that was previously passed in is no longer valid.

The ldi_close() function returns 0 for success. EINVAL is returned for invalid input parameters. Otherwise, any other error number may be returned by the device.

The ldi_open_by_dev() and ldi_open_by_devid() functions return 0 upon success. If a failure occurs before the device is open, possible return values are shown below. Otherwise any other error number may be returned by the device. EINVAL

ENODEV ENXIO

The ldi_open_by_name() function returns 0 upon success. If a failure occurs before the device is open, possible return values are shown below. Otherwise any other error number may be returned by the device. EINVAL

ENODEV EACCES ENXIO These functions may be called from user or kernel context.

These functions should not be called from a device's attach, detach, or power entry point. This could result in a system crash or deadlock.

scsi_vhci (4D), ldi_ident_from_dev (9F), ldi_ident_from_dip (9F), ldi_ident_from_stream (9F) Use only OTYP_CHR or OTYP_BLK options when you use the ldi_open_by_dev() and ldi_open_by_devid() functions to open a device. Other flags, including OTYP_LYR, have been deprecated and should not be used with these interfaces.

The caller should be aware of cases when multiple paths to a single device may exist. (This can occur for scsi disk devices if scsi_vhci(4D)) is disabled or a disk is connected to multiple controllers not supported by scsi_vhci(4D).

In these cases, ldi_open_by_devid() returns a device handle that corresponds to a particular path to a target device. This path may not be the same across multiple calls to ldi_open_by_devid(). Device handles associated with the same device but different access paths should have different filesystem device paths and dev_t values.

In the cases where multiple paths to a device exist and access to the device has not been virtualized via MPXIO (as with scsi disk devices not accessed via scsi_vhci(4D)), the LDI does not provide any path fail-over capabilities. If the caller wishes to do their own path management and failover they should open all available paths to a device via ldi_open_by_name().