A basic set of methods required for all device drivers. More...

Variables
INTERFACE	device

	CODE

METHOD int	probe
	Probe to see if a device matches a driver. More...

STATICMETHOD void	identify
	Allow a device driver to detect devices not otherwise enumerated. More...

device_t	parent

METHOD int	attach
	Attach a device to a device driver. More...

METHOD int	detach
	Detach a driver from a device. More...

METHOD int	shutdown
	Called during system shutdown. More...

DEFAULT	null_shutdown

METHOD int	suspend
	This is called by the power-management subsystem when a suspend has been requested by the user or by some automatic mechanism. More...

DEFAULT	null_suspend

METHOD int	resume
	This is called when the system resumes after a suspend. More...

DEFAULT	null_resume

METHOD int	quiesce
	This is called when the driver is asked to quiesce itself. More...

DEFAULT	null_quiesce

Detailed Description

A basic set of methods required for all device drivers.

The device interface is used to match devices to drivers during autoconfiguration and provides methods to allow drivers to handle system-wide events such as suspend, resume or shutdown.

Variable Documentation

METHOD int attach

Initial value:

{

device_t dev

Attach a device to a device driver.

Normally only called via device_probe_and_attach(), this is called when a driver has succeeded in probing against a device. This method should initialise the hardware and allocate other system resources (e.g. devfs entries) as required.

To include this method in a device driver, use a line like this in the driver's method list:

1 KOBJMETHOD(device_attach, foo_attach)

Parameters

dev	the device to probe

Return values

0	success
non-zero	if some kind of error was detected during the attach, a regular unix error code should be returned to indicate the type of error

See also: DEVICE_PROBE()

Definition at line 197 of file device_if.m.

CODE

Initial value:

{
        static int null_shutdown(device_t dev)
        {
            return 0;
        }
        static int null_suspend(device_t dev)
        {
            return 0;
        }
        static int null_resume(device_t dev)
        {
            return 0;
        }
        static int null_quiesce(device_t dev)
        {
            return EOPNOTSUPP;
        }
}

Definition at line 45 of file device_if.m.

METHOD int detach

Initial value:

{

device_t dev

Detach a driver from a device.

This can be called if the user is replacing the driver software or if a device is about to be physically removed from the system (e.g. for removable hardware such as USB or PCCARD).

To include this method in a device driver, use a line like this in the driver's method list:

1 KOBJMETHOD(device_detach, foo_detach)

Parameters

dev	the device to detach

Return values

0	success
non-zero	the detach could not be performed, e.g. if the driver does not support detaching.

See also: DEVICE_ATTACH()

Definition at line 223 of file device_if.m.

INTERFACE device

Definition at line 40 of file device_if.m.

STATICMETHOD void identify

Initial value:

{

driver_t *driver

Allow a device driver to detect devices not otherwise enumerated.

The DEVICE_IDENTIFY() method is used by some drivers (e.g. the ISA bus driver) to help populate the bus device with a useful set of child devices, normally by calling the BUS_ADD_CHILD() method of the parent device. For instance, the ISA bus driver uses several special drivers, including the isahint driver and the pnp driver to create child devices based on configuration hints and PnP bus probes respectively.

Many bus drivers which support true plug-and-play do not need to use this method at all since child devices can be discovered automatically without help from child drivers.

To include this method in a device driver, use a line like this in the driver's method list:

1 KOBJMETHOD(device_identify, foo_identify)

Parameters

driver	the driver whose identify method is being called
parent	the parent device to use when adding new children

Definition at line 169 of file device_if.m.

DEFAULT null_quiesce

Definition at line 318 of file device_if.m.

DEFAULT null_resume

Definition at line 292 of file device_if.m.

DEFAULT null_shutdown

Definition at line 243 of file device_if.m.

DEFAULT null_suspend

Definition at line 270 of file device_if.m.

device_t parent

Definition at line 171 of file device_if.m.

Referenced by bus_child_location_str(), bus_child_pnpinfo_str(), bus_get_dma_tag(), cpufreq_attach(), cpuset_shadow(), devclass_driver_added(), devclass_driver_deleted(), do_unlink(), make_device(), mqfs_add_node(), mqfs_destroy(), proc_realparent(), proc_reparent(), sysctl_add_oid(), sysctl_move_oid(), sysctl_register_oid(), and TAILQ_HEAD().

METHOD int probe

Initial value:

{

device_t dev

Probe to see if a device matches a driver.

Users should not call this method directly. Normally, this is called via device_probe_and_attach() to select a driver calling the DEVICE_PROBE() of all candidate drivers and attach the winning driver (if any) to the device.

This function is used to match devices to device drivers. Typically, the driver will examine the device to see if it is suitable for this driver. This might include checking the values of various device instance variables or reading hardware registers.

In some cases, there may be more than one driver available which can be used for a device (for instance there might be a generic driver which works for a set of many types of device and a more specific driver which works for a subset of devices). Because of this, a driver should not assume that it will be the driver that attaches to the device even if it returns a success status from DEVICE_PROBE(). In particular, a driver must free any resources which it allocated during the probe before returning. The return value of DEVICE_PROBE() is used to elect which driver is used - the driver which returns the largest non-error value wins the election and attaches to the device. Common non-error values are described in the DEVICE_PROBE(9) manual page.

If a driver matches the hardware, it should set the device description string using device_set_desc() or device_set_desc_copy(). This string is used to generate an informative message when DEVICE_ATTACH() is called.

As a special case, if a driver returns zero, the driver election is cut short and that driver will attach to the device immediately. This should rarely be used.

For example, a probe method for a PCI device driver might look like this:

 int
 foo_probe(device_t dev)
 {
         if (pci_get_vendor(dev) == FOOVENDOR &&
             pci_get_device(dev) == FOODEVICE) {
                 device_set_desc(dev, "Foo device");
                 return (BUS_PROBE_DEFAULT);
         }
         return (ENXIO);
 }

To include this method in a device driver, use a line like this in the driver's method list:

1 KOBJMETHOD(device_probe, foo_probe)

Parameters

dev	the device to probe

Return values

0	if this is the only possible driver for this device
negative	if the driver can match this device - the least negative value is used to select the driver
ENXIO	if the driver does not match the device
positive	if some kind of error was detected during the probe, a regular unix error code should be returned to indicate the type of error

See also: DEVICE_ATTACH(), pci_get_vendor(), pci_get_device()

Definition at line 140 of file device_if.m.

METHOD int quiesce

Initial value:

{

device_t dev

This is called when the driver is asked to quiesce itself.

The driver should arrange for the orderly shutdown of this device. All further access to the device should be curtailed. Soon there will be a request to detach, but there won't necessarily be one.

To include this method in a device driver, use a line like this in the driver's method list:

1 KOBJMETHOD(device_quiesce, foo_quiesce)

Parameters

dev	the device being quiesced

Return values

0	success
non-zero	an error occurred while attempting to quiesce the device

See also: DEVICE_DETACH()

Definition at line 316 of file device_if.m.

METHOD int resume

Initial value:

{

device_t dev

This is called when the system resumes after a suspend.

To include this method in a device driver, use a line like this in the driver's method list:

1 KOBJMETHOD(device_resume, foo_resume)

Parameters

dev	the device being resumed

Return values

0	success
non-zero	an error occurred while attempting to restore the device from suspension

See also: DEVICE_SUSPEND()

Definition at line 290 of file device_if.m.

METHOD int shutdown

Initial value:

{

device_t dev

Called during system shutdown.

This method allows drivers to detect when the system is being shut down. Some drivers need to use this to place their hardware in a consistent state before rebooting the computer.

To include this method in a device driver, use a line like this in the driver's method list:

1 KOBJMETHOD(device_shutdown, foo_shutdown)

Definition at line 241 of file device_if.m.

METHOD int suspend

Initial value:

{

device_t dev

This is called by the power-management subsystem when a suspend has been requested by the user or by some automatic mechanism.

This gives drivers a chance to veto the suspend or save their configuration before power is removed.

To include this method in a device driver, use a line like this in the driver's method list:

1 KOBJMETHOD(device_suspend, foo_suspend)

Parameters

dev	the device being suspended

Return values

0	success
non-zero	an error occurred while attempting to prepare the device for suspension

See also: DEVICE_RESUME()

Definition at line 268 of file device_if.m.

Variables

Detailed Description

Variable Documentation