Intro(9E)

NAME | DESCRIPTION

NAME

Intro– introduction to device driver entry points

DESCRIPTION

Section 9E describes the entry-point routines a developer may include in a device driver. These are called entry-point because they provide the calling and return syntax from the kernel into the driver. Entry-points are called, for instance, in response to system calls, when the driver is loaded, or in response to STREAMS events.

Kernel functions usable by the driver are described in section 9F.

In this section, reference pages contain the following headings:

• NAME describes the routine's purpose.

• SYNOPSIS summarizes the routine's calling and return syntax.

• INTERFACE LEVEL describes any architecture dependencies. It also indicates whether the use of the entry point is required, optional, or discouraged.

• ARGUMENTS describes each of the routine's arguments.

• DESCRIPTION provides general information about the routine.

• RETURN VALUES describes each of the routine's return values.

• SEE ALSO gives sources for further information.

Overview of Driver Entry-Point Routines and Naming Conventions

By convention, a prefix string is added to the driver routine names. For a driver with the prefix prefix, the driver code may contain routines named prefixopen, prefixclose, prefixread, prefixwrite, and so forth. All global variables associated with the driver should also use the same prefix.

All routines and data should be declared as static.

Every driver MUST include <sys/ddi.h> and <sys/sunddi.h>, in that order, and after all other include files.

The following table summarizes the STREAMS driver entry points described in this section.

Routine	Type
put	DDI/DKI
srv	DDI/DKI

The following table summarizes the driver entry points described in this section.

Routine	Type
_fini	Solaris DDI
_info	Solaris DDI
_init	Solaris DDI
aread	Solaris DDI
attach	Solaris DDI
awrite	Solaris DDI
chpoll	DDI/DKI
close	DDI/DKI
detach	Solaris DDI
devmap	Solaris DDI
devmap_access	Solaris DDI
devmap_contextmgt	Solaris DDI
devmap_dup	Solaris DDI
devmap_map	Solaris DDI
devmap_unmap	Solaris DDI
dump	Solaris DDI
getinfo	Solaris DDI
identify	Solaris DDI
ioctl	DDI/DKI
ks_update	Solaris DDI
mapdev_access	Solaris DDI
mapdev_dup	Solaris DDI
mapdev_free	Solaris DDI
mmap	DKI only
open	DDI/DKI
power	Solaris DDI
print	DDI/DKI
probe	Solaris DDI
prop_op	Solaris DDI
read	DDI/DKI
segmap	DKI only
strategy	DDI/DKI
tran_abort	Solaris DDI
tran_destroy_pkt	Solaris DDI
tran_dmafree	Solaris DDI
tran_getcap	Solaris DDI
tran_init_pkt	Solaris DDI
tran_reset	Solaris DDI
tran_reset_notify	Solaris DDI
tran_setcap	Solaris DDI
tran_start	Solaris DDI
tran_sync_pkt	Solaris DDI
tran_tgt_free	Solaris DDI
tran_tgt_init	Solaris DDI
tran_tgt_probe	Solaris DDI
write	DDI/DKI

The following table lists the error codes returned by a driver routine when it encounters an error. The error values are listed in alphabetic order and are defined in sys/errno.h. In the driver open(9E), close(9E), ioctl(9E), read(9E), and write(9E) routines, errors are passed back to the user by calling bioerror(9F) to set b_flags to the proper error code. In the driver strategy(9E) routine, errors are passed back to the user by setting the b_error member of the buf(9S) structure to the error code. For STREAMS ioctl routines, errors should be sent upstream in an M_IOCNAK message. For STREAMS read() and write() routines, errors should be sent upstream in an M_ERROR message. The driver print routine should not return an error code because the function that it calls, cmn_err(9F), is declared as void (no error is returned).

Error Value	Error Description
EAGAIN	Kernel resources, such as the buf structure or cache memory, are not available at this time (device may be busy, or the system resource is not available). This is used in open, ioctl, read, write, and strategy.
EFAULT	An invalid address has been passed as an argument; memory addressing error. This is used in open, close, ioctl, read, write, and strategy.
EINTR	Sleep interrupted by signal. This is used in open, close, ioctl, read, write, and strategy.
EINVAL	An invalid argument was passed to the routine. This is used in open, ioctl, read, write, and strategy.
EIO	A device error occurred; an error condition was detected in a device status register (the I/O request was valid, but an error occurred on the device). This is used in open, close, ioctl, read, write, and strategy.
ENXIO	An attempt was made to access a device or subdevice that does not exist (one that is not configured); an attempt was made to perform an invalid I/O operation; an incorrect minor number was specified. This is used in open, close, ioctl, read, write, and strategy.
EPERM	A process attempting an operation did not have required permission. This is used in open, ioctl, read, write, and strategy.
EROFS	An attempt was made to open for writing a read-only device. This is used in open.

The table below cross references error values to the driver routines from which the error values can be returned.

open	close	ioctl	read, write and strategy
EAGAIN	EFAULT	EAGAIN	EAGAIN
EFAULT	EINTR	EFAULT	EFAULT
EINTR	EIO	EINTR	EINTR
EINVAL	ENXIO	EINVAL	EINVAL
EIO		EIO	EIO
ENXIO		ENXIO	ENXIO
EPERM		EPERM
EROFS

NAME | DESCRIPTION