Writing Device Drivers
Previous Next

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 Point

Usage

Description

devmap(9E)

Required

Validates and translates virtual mapping for a memory-mapped device. Additional information: Exporting the Mapping

devmap_access(9E)

Optional

Notifies drivers when an access is made to a mapping with validation or protection problems. Additional information: devmap_access() Entry Point

devmap_contextmgt(9E)

Required

Performs device context switching on a mapping. Additional information: devmap_contextmgt() Entry Point

devmap_dup(9E)

Optional

Duplicates a device mapping. Additional information: devmap_dup() Entry Point

devmap_map(9E)

Optional

Creates a device mapping. Additional information: devmap_map() Entry Point

devmap_unmap(9E)

Optional

Cancels a device mapping. Additional information: devmap_unmap() Entry Point

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 Point

Usage

Description

gldm_get_stats(9E)

Optional

Gathers statistics from private counters in a generic LAN driver. Updates the gld_stats(9S) structure. Additional information: gldm_get_stats() Entry Point

gldm_intr(9E)

See Description

Receives calls for potential interrupts to a generic LAN driver (GLD). Required if gld_intr(9F) is used as interrupt handler. Additional information: gldm_intr() Entry Point

gldm_ioctl(9E)

Optional

Implements device-specific commands for a generic LAN driver (GLD). Additional information: gldm_ioctl() Entry Point

gldm_reset(9E)

Required

Resets a generic LAN driver (GLD) to the initial state. Additional information: gldm_reset() Entry Point

gldm_send(9E)

Required

Queues a packet to a generic LAN driver (GLD) for transmission. Additional information: gldm_send() Entry Point

gldm_set_mac_addr(9E)

Required

Sets the physical address that the generic LAN driver (GLD) uses to receive data. Additional information: gldm_set_mac_addr() Entry Point

gldm_set_multicast(9E)

Optional

Enables and disables device-level reception of specific multicast addresses for generic LAN driver (GLD). Additional information: gldm_set_multicast() Entry Point

gldm_set_promiscuous(9E)

Required

Enables and disables promiscuous mode for a generic LAN driver (GLD) to receive packets on the medium. Additional information: gldm_set_promiscuous() Entry Point

gldm_start(9E)

Required

Enables a generic LAN driver (GLD) to generate interrupts. Prepares the driver to call gld_recv(9F) to deliver received data packets. Additional information: gldm_start() Entry Point

gldm_stop(9E)

Required

Disables a generic LAN driver (GLD) from generating interrupts and from calling gld_recv(9F). Additional information: gldm_stop() Entry Point

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 Point

Usage

Description

tran_abort(9E)

Required

Aborts a specified SCSI command that has been transported to a SCSI Host Bus Adapter (HBA) driver. Additional information: tran_abort() Entry Point

tran_bus_reset(9E)

Optional

Resets a SCSI bus. Additional information: tran_bus_reset() Entry Point

tran_destroy_pkt(9E)

Required

Frees resources that are allocated for a SCSI packet. Additional information: tran_destroy_pkt() Entry Point

tran_dmafree(9E)

Required

Frees DMA resources that have been allocated for a SCSI packet. Additional information: tran_dmafree() Entry Point

tran_getcap(9E)

Required

Gets the current value of a specific capability that is provided by the HBA driver. Additional information: tran_getcap() Entry Point

tran_init_pkt(9E)

Required

Allocate and initialize resources for a SCSI packet. Additional information: Resource Allocation

tran_quiesce(9E)

Optional

Stop all activity on a SCSI bus, typically for dynamic reconfiguration. Additional information: Dynamic Reconfiguration

tran_reset(9E)

Required

Resets a SCSI bus or target device. Additional information: tran_reset() Entry Point

tran_reset_notify(9E)

Optional

Requests notification of a SCSI target device for a bus reset. Additional information: tran_reset_notify() Entry Point

tran_setcap(9E)

Required

Sets the value of a specific capability that is provided by the SCSI HBA driver. Additional information: tran_setcap() Entry Point

tran_start(9E)

Required

Requests the transport of a SCSI command. Additional information: tran_start() Entry Point

tran_sync_pkt(9E)

Required

Synchronizes the view of data by an HBA driver or device. Additional information: tran_sync_pkt() Entry Point

tran_tgt_free(9E)

Optional

Requests allocated SCSI HBA resources to be freed on behalf of a target device. Additional information:

tran_tgt_init(9E)

Optional

Requests SCSI HBA resources to be initialized on behalf of a target device. Additional information:

tran_tgt_probe(9E)

Optional

Probes a specified target on a SCSI bus. Additional information: tran_tgt_probe() Entry Point

tran_unquiesce(9E)

Optional

Resumes I/O activity on a SCSI bus after tran_quiesce(9E) has been called, typically for dynamic reconfiguration. Additional information: Dynamic Reconfiguration

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.

Previous Next