Device Driver Entry Points
This section provides lists of entry points for the following categories:
Entry Points Common to All Drivers
Some operations can be performed by any type of driver, such as
the functions that are required for module loading and for the required autoconfiguration entry
points. This section discusses types of entry points that are common to all
drivers. The common entry points are listed in Summary of Common Entry Points with links to
man pages and other relevant discussions.
Device Access Entry Points
Drivers for character and block devices export the cb_ops(9S) structure, which defines the
driver entry points for block device access and character device access. Both
types of drivers are required to support the open(9E) and close(9E) entry
points. Block drivers are required to support strategy(9E), while character drivers can choose
to implement whatever mix of read(9E), write(9E), ioctl(9E), mmap(9E), or devmap(9E) entry
points is appropriate for the type of device. Character drivers can also
support a polling interface through chpoll(9E). Asynchronous I/O is supported through aread(9E)
and awrite(9E) for block drivers and those drivers that can use both block
and character file systems.
Loadable Module Entry Points
All drivers are required to implement the loadable module entry points _init(9E), _fini(9E),
and _info(9E) to load, unload, and report information about the driver module.
Drivers should allocate and initialize any global resources in _init(9E). Drivers should release
their resources in _fini(9E).
Note - In the Solaris OS, only the loadable module routines must be visible outside
the driver object module. Other routines can have the storage class static.
Autoconfiguration Entry Points
Drivers are required to implement the attach(9E), detach(9E), and getinfo(9E) entry points for
device autoconfiguration. Drivers can also implement the optional entry point probe(9E) in cases
where devices do not identify themselves during boot-up, such as SCSI target devices.
See Chapter 6, Driver Autoconfiguration for more information on these routines.
Kernel Statistics Entry Points
The Solaris platform provides a rich set of interfaces to maintain and export
kernel-level statistics, also known as kstats. Drivers are free to use these interfaces
to export driver and device statistics that can be used by user applications
to observe the internal state of the driver. Two entry points are
provided for working with kernel statistics:
ks_snapshot(9E) captures kstats at a specific time.
ks_update(9E) can be used to update kstat data at will. ks_update() is useful in situations where a device is set up to track kernel data but extracting that data is time-consuming.
For further information, see the kstat_create(9F) and kstat(9S) man pages. See also
Kernel Statistics.
Power Management Entry Point
Drivers for hardware devices that provide Power Management functionality can support the optional
power(9E) entry point. See Chapter 12, Power Management for details about this entry point.
Summary of Common Entry Points
The following table lists entry points that can be used by all
types of drivers.
Table 1-1 Entry Points for All Driver Types
Category / Entry Point |
Usage |
Description |
|---|
cb_ops Entry Points |
|
|
open(9E) |
Required |
Gets access to a device. Additional information:
|
close(9E) |
Required |
Gives
up access to a device. The version of close() for STREAMS drivers
has a different signature than character and block drivers. Additional information:
|
Loadable Module Entry Points |
|
|
_init(9E) |
Required |
Initializes a loadable
module. Additional information: Loadable Driver Interfaces |
_fini(9E) |
Required |
Prepares a loadable module for unloading. Required for all
driver types. Additional information: Loadable Driver Interfaces |
_info(9E) |
Required |
Returns information about a loadable module. Additional information: Loadable Driver Interfaces |
Autoconfiguration Entry Points |
|
|
attach(9E) |
Required |
Adds
a device to the system as part of initialization. Also used to resume
a system that has been suspended. Additional information: attach() Entry Point |
detach(9E) |
Required |
Detaches a device from
the system. Also, used to suspend a device temporarily. Additional information: detach() Entry Point |
getinfo(9E) |
Required |
Gets device
information that is specific to the driver, such as the mapping between a
device number and the corresponding instance. Additional information:
|
probe(9E) |
See Description |
Determines if a non-self-identifying device
is present. Required for a device that cannot identify itself. Additional information:
|
Kernel Statistics Entry Points |
|
|
ks_snapshot(9E) |
Optional |
Takes a
snapshot of kstat(9S) data. Additional information: Kernel Statistics |
ks_update(9E) |
Optional |
Updates kstat(9S) data dynamically. Additional information: Kernel Statistics |
Power Management Entry Points |
|
|
power(9E) |
Required |
Sets the
power level of a device. If not used, set to NULL. Additional information:
power() Entry Point |
Miscellaneous Entry Points |
|
|
prop_op(9E) |
See Description |
Reports driver property information. Required unless ddi_prop_op(9F) is substituted. Additional information:
|
dump(9E) |
See
Description |
Dumps memory to a device during system failure. Required for any device that
is to be used as the dump device during a panic. Additional
information:
|
identify(9E) |
Obsolete |
Do not use this entry point. Assign nulldev(9F) to this entry point
in the dev_ops structure. |
Entry Points for Block Device Drivers
Devices that support a file system are known as block devices. Drivers written for these
devices are known as block device drivers. Block device drivers take a file
system request, in the form of a buf(9S) structure, and issue the
I/O operations to the disk to transfer the specified block. The main interface
to the file system is the strategy(9E) routine. See Chapter 16, Drivers for Block Devices for more information.
A block device driver can also provide a character driver interface to enable
utility programs to bypass the file system and to access the device directly.
This device access is commonly referred to as the raw interface to a
block device.
The following table lists additional entry points that can be used by block
device drivers. See also Entry Points Common to All Drivers.
Table 1-2 Additional Entry Points for Block Drivers
Entry Point |
Usage |
Description |
|---|
aread(9E) |
Optional |
Performs an asynchronous read. Drivers that do
not support an aread() entry point should use the nodev(9F) error return
function. Additional information:
|
awrite(9E) |
Optional |
Performs an asynchronous write. Drivers that do not support an awrite()
entry point should use the nodev(9F) error return function. Additional information:
|
print(9E) |
Required |
Displays a driver
message on the system console. Additional information: print() Entry Point (Block Drivers) |
strategy(9E) |
Required |
Perform block I/O. Additional information:
|
Entry Points for Character Device Drivers
Character device drivers normally perform I/O in a byte stream. Examples of devices
that use character drivers include tape drives and serial ports. Character device drivers
can also provide additional interfaces not present in block drivers, such as I/O
control (ioctl) commands, memory mapping, and device polling. See Chapter 15, Drivers for Character Devices for more information.
The main task of any device driver is to perform I/O, and
many character device drivers do what is called byte-stream or character I/O. The
driver transfers data to and from the device without using a specific device
address. This type of transfer is in contrast to block device drivers, where
part of the file system request identifies a specific location on the device.
The read(9E) and write(9E) entry points handle byte-stream I/O for standard character drivers.
See I/O Request Handling for more information.
The following table lists additional entry points that can be used by character
device drivers. For other entry points, see Entry Points Common to All Drivers.
Table 1-3 Additional Entry Points for Character Drivers
Entry Point |
Usage |
Description |
|---|
chpoll(9E) |
Optional |
Polls events for a
non-STREAMS character driver. Additional information: Multiplexing I/O on File Descriptors |
ioctl(9E) |
Optional |
Performs a range of I/O commands for
character drivers. ioctl() routines must make sure that user data is copied into
or out of the kernel address space explicitly using copyin(9F), copyout(9F), ddi_copyin(9F), and
ddi_copyout(9F), as appropriate. Additional information:
|
read(9E) |
Required |
Reads data from a device. Additional information:
|
segmap(9E) |
Optional |
Maps device
memory into user space. Additional information:
|
write(9E) |
Required |
Writes data to a device. Additional information:
|
Entry Points for STREAMS Device Drivers
STREAMS is a separate programming model for writing a character driver. Devices that
receive data asynchronously, such as terminal and network devices, are suited to a
STREAMS implementation. STREAMS device drivers must provide the loading and autoconfiguration support described
in Chapter 6, Driver Autoconfiguration. See the STREAMS Programming Guide for additional information on how to write STREAMS drivers.
The following table lists additional entry points that can be used by STREAMS
device drivers. For other entry points, see Entry Points Common to All Drivers and Entry Points for Character Device Drivers.
Table 1-4 Entry Points for STREAMS Drivers
Entry Point |
Usage |
Description |
|---|
put(9E) |
See Description |
Coordinates
the passing of messages from one queue to the next queue in a
stream. Required, except for the side of the driver that reads data. Additional
information: STREAMS Programming Guide |
srv(9E) |
Required |
Manipulate messages in a queue. Additional information: STREAMS Programming Guide |
Entry Points for Memory Mapped Devices
For certain devices, such as frame buffers, providing application programs with direct access
to device memory is more efficient than byte-stream I/O. Applications can map device memory
into their address spaces using the mmap(2) system call. To support memory
mapping, device drivers implement segmap(9E) and devmap(9E) entry points. For information on devmap(9E), see Chapter 10, Mapping Device and Kernel Memory.
For information on segmap(9E), see Chapter 15, Drivers for Character Devices.
Drivers that define the devmap(9E) entry point usually do not define read(9E) and
write(9E) entry points, because application programs perform I/O directly to the devices after
calling mmap(2).
The following table lists additional entry points that can be used by character
device drivers that use the devmap framework to perform memory mapping. For other
entry points, see Entry Points Common to All Drivers and Entry Points for Character Device Drivers.
Table 1-5 Entry Points for Character Drivers That Use devmap for Memory Mapping
Entry Points for the Generic LAN Device (GLD) Driver
The following table lists additional entry points that can be used by the
general LAN driver (GLD). For more information on GLD drivers, see the
gld(9E), gld(7D), and gld_mac_info(9S) man pages. For other entry points, see Entry Points Common to All Drivers and
Entry Points for Character Device Drivers.
Table 1-6 Additional Entry Points for the Generic LAN Driver
Entry Points for SCSI HBA Drivers
The following table lists additional entry points that can be used by SCSI
HBA device drivers. For information on the SCSI HBA transport structure, see scsi_hba_tran(9S).
For other entry points, see Entry Points Common to All Drivers and Entry Points for Character Device Drivers.
Table 1-7 Additional Entry Points for SCSI HBA Drivers
Entry Points for PC Card Drivers
The following table lists additional entry points that can be used by PC
Card device drivers. For other entry points, see Entry Points Common to All Drivers and Entry Points for Character Device Drivers.
Table 1-8 Entry Points for PC Card Drivers Only
Entry Point |
Usage |
Description |
|---|
csx_event_handler(9E) |
Required |
Handles
events for a PC Card driver. The driver must call the csx_RegisterClient(9F)
function explicitly to set the entry point instead of using a structure field
like cb_ops. |
