NAME

Intro, 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

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. also use the same prefix.

and Naming Conventions

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
attach             Solaris DDI
chpoll             DDI/DKI
close              DDI/DKI
detach             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

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_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 table below lists the error codes that should be returned by a driver routine when an error is encountered. It lists the error values in alphabetic order. All the error values 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 returning the value. 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, as the function that it calls, cmn_err(9F), is declared as void (no error is returned).

Error

Use in these

Value........Error Description......Driver Routines (9E)

EAGAIN

Kernel resources, such as the buf struc-

open, ioctl, read, write,

ture or cache memory, are not available

                                                        strategy

at this time (device may be busy, or the

system resource is not available).

EFAULT

An invalid address has been passed as

open, close, ioctl, read,

an argument; memory addressing error.

                                                        write, strategy
EINTR       Sleep interrupted by signal.                open, close, ioctl, read,
                                                        write, strategy
EINVAL      An invalid argument was passed to the

open, ioctl, read, write,

routine.

                                                        strategy

EIO

A device error occurred; an error condi-

open, close, ioctl, read,

tion was detected in a device status

                                                        write, strategy

register (the I/O request was valid, but

an error occurred on the device).

ENXIO

An attempt was made to access a device

open, close, ioctl, read,

or subdevice that does not exist (one

                                                        write, strategy

that is not configured); an attempt was

made to perform an invalid I/O opera-

tion; an incorrect minor number was

specified.

EPERM

A process attempting an operation did

open, ioctl, read, write,

not have required permission.

                                                        close

EROFS

An attempt was made to open for writ-

open

ing a read-only device.

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

			read ,write,
open	close	ioctl	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 EROFS		EPERM

Name                Appears on Page       Description

_fini

_fini(9E)

loadable module configuration entry points

_info               _fini(9E)              loadable module configuration entry points
_init               _fini(9E)              loadable module configuration entry points
attach              attach(9E)            attach a device to the system
chpoll              chpoll(9E)            poll entry point for a non-STREAMS
                                          character driver
close               close(9E)             relinquish access to a device
detach              detach(9E)            detach a device
dump                dump(9E)              dump memory to device during system failure
getinfo             getinfo(9E)           get device driver information
identify            identify(9E)          claim to drive a device
ioctl               ioctl(9E)             control a character device
ks_update           ks_update(9E)         dynamically update kstats
mapdev_access       mapdev_access(9E)     device mapping access entry point
mapdev_dup          mapdev_dup (9E)       device mapping duplication entry point
mapdev_free         mapdev_free(9E)       device mapping free entry point
mmap                mmap(9E)              check virtual mapping for memory mapped
                                          device
open                open(9E)              gain access to a device
print               print(9E)             display a driver message on system console
probe               probe(9E)             determine if a non-self-identifying device
                                          is present
prop_op             prop_op(9E)           report driver property information
put                 put(9E)               receive messages from the preceding queue
read                read (9E)             read data from a device
segmap              segmap (9E)           map device memory into user space
srv                 srv(9E)               service queued messages
strategy            strategy(9E)          perform block I/O
tran_abort          tran_abort(9E)        abort a SCSI command
tran_destroy_pkt    tran_init_pkt(9E)     SCSI HBA packet preparation and
                                          deallocation
tran_dmafree        tran_dmafree(9E)      SCSI HBA DMA deallocation entry point
tran_getcap         tran_getcap(9E)       get/set SCSI transport capability
tran_init_pkt       tran_init_pkt(9E)     SCSI HBA packet preparation and
                                          deallocation
tran_reset          tran_reset(9E)        reset a SCSI bus or target
tran_setcap         tran_getcap(9E)       get/set SCSI transport capability
tran_start          tran_start(9E)        request to transport a SCSI command
tran_sync_pkt       tran_sync_pkt(9E)     SCSI HBA memory synchronization entry point
tran_tgt_free       tran_tgt_free(9E)     request to free HBA resources allocated on
                                          behalf of a target

tran_tgt_init

tran_tgt_init(9E)

request to initialize HBA resources on

behalf of a particular target

tran_tgt_probe

tran_tgt_probe(9E)

request to probe SCSI bus for a particular

target

write

write(9E)

write data to a device