test

Writing Device Drivers

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 Oracle 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 Oracle 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:

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.

System Quiesce Entry Point

A driver that manages devices must implement the quiesce(9E) entry point. Drivers that do not manage devices can set the devo_quiesce field in the dev_ops structure to ddi_quiesce_not_needed(). The quiesce() function can be called only when the system is single-threaded at high PIL (priority interrupt level) with preemption disabled. Therefore, this function must not be blocked. If a device has a defined reset state configuration, the driver should return that device to that reset state as part of the quiesce operation. An example of this case is Fast Reboot, where firmware is bypassed when booting to a new operating system image.

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 Point

   

power(9E)

Required 

Sets the power level of a device. If not used, set to NULL. Additional information: power() Entry Point

System Quiesce Entry Point

   

quiesce(9E)

See Description 

Quiesces a device so that the device no longer generates interrupts or modifies or accesses memory. 

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.