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

Variables
INTERFACE	device

	HEADER

	PROLOG
	Probe to see if a device matches a driver. More...

	EPILOG

METHOD int	probe

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

device_t	parent

METHOD int	attach

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

METHOD void *	register
	This is called when the driver is asked to register handlers. More...

DEFAULT	null_register

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

◆ attach

METHOD int attach

Initial value:

{

device_t dev

Definition at line 219 of file device_if.m.

◆ detach

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:

KOBJMETHOD(device_detach, foo_detach)

device_detach

int device_detach(device_t dev)

Detach a driver from a device.

Definition: subr_bus.c:3075

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 245 of file device_if.m.

◆ device

INTERFACE device

Definition at line 40 of file device_if.m.

◆ EPILOG

EPILOG

Initial value:

{

TSEXIT2(device_get_name(dev))

device_get_name

const char * device_get_name(device_t dev)

Return the name of the device's devclass or NULL if there is none.

Definition: subr_bus.c:2342

Definition at line 153 of file device_if.m.

◆ HEADER

HEADER

Definition at line 43 of file device_if.m.

◆ identify

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:

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 185 of file device_if.m.

◆ null_quiesce

DEFAULT null_quiesce

Definition at line 340 of file device_if.m.

◆ null_register

DEFAULT null_register

Definition at line 361 of file device_if.m.

◆ null_resume

DEFAULT null_resume

Definition at line 314 of file device_if.m.

◆ null_shutdown

DEFAULT null_shutdown

Definition at line 265 of file device_if.m.

◆ null_suspend

DEFAULT null_suspend

Definition at line 292 of file device_if.m.

◆ parent

device_t parent

Definition at line 187 of file device_if.m.

Referenced by adopt(), bus_child_location(), bus_child_pnpinfo(), bus_dma_template_init(), bus_generic_get_device_path(), bus_get_bus_tag(), bus_get_cpus(), bus_get_dma_tag(), cpufreq_attach(), cpuset_create(), cpuset_init(), cpuset_setproc_maskthread(), cpuset_setproc_setthread_mask(), cpuset_setproc_test_maskthread(), cpuset_shadow(), cpuset_testshadow(), devclass_driver_added(), devclass_driver_deleted(), devctl2_ioctl(), do_unlink(), domainset_restrict(), domainset_valid(), firmware_register(), intr_child_irq_handler(), intr_pic_add_handler(), isitmychild(), itismychild(), linker_load_module(), make_device(), mqfs_add_node(), mqfs_create_file(), mqfs_destroy(), mqfs_fixup_dir(), pctrie_remove(), pidctrl_init_sysctl(), prison_add_allow(), proc_add_orphan(), proc_realparent(), proc_reparent(), sysctl_add_oid(), sysctl_move_oid(), sysctl_register_oid(), sysctl_remove_name(), TAILQ_HEAD(), witness_lock_order_add(), witness_lock_order_check(), and witness_lock_order_get().

◆ probe

METHOD int probe

Initial value:

{

device_t dev

Definition at line 156 of file device_if.m.

◆ PROLOG

PROLOG

Initial value:

{

TSENTER2(device_get_name(dev))

Probe to see if a device matches a driver.

Attach a device to a device 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:

KOBJMETHOD(device_probe, foo_probe)

device_probe

int device_probe(device_t dev)

Probe a device, and return this status.

Definition: subr_bus.c:2943

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()

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:

KOBJMETHOD(device_attach, foo_attach)

device_attach

int device_attach(device_t dev)

Attach a device driver to a device.

Definition: subr_bus.c:3015

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 150 of file device_if.m.

◆ quiesce

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:

KOBJMETHOD(device_quiesce, foo_quiesce)

device_quiesce

int device_quiesce(device_t dev)

Tells a driver to quiesce itself.

Definition: subr_bus.c:3131

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 338 of file device_if.m.

◆ register

METHOD void* register

Initial value:

{

device_t dev

This is called when the driver is asked to register handlers.

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

KOBJMETHOD(device_register, foo_register)

Parameters

dev	the device for which handlers are being registered

Return values

NULL	method not implemented
non-NULL	a pointer to implementation specific static driver state

Definition at line 359 of file device_if.m.

◆ resume

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:

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 312 of file device_if.m.

◆ shutdown

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:

KOBJMETHOD(device_shutdown, foo_shutdown)

device_shutdown

int device_shutdown(device_t dev)

Notify a device of system shutdown.

Definition: subr_bus.c:3151

Definition at line 263 of file device_if.m.

◆ suspend

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:

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 290 of file device_if.m.

Variables

Detailed Description

Variable Documentation

◆ attach

◆ detach

◆ device

◆ EPILOG

◆ HEADER

◆ identify

◆ null_quiesce

◆ null_register

◆ null_resume

◆ null_shutdown

◆ null_suspend

◆ parent

◆ probe

◆ PROLOG

◆ quiesce

◆ register

◆ resume

◆ shutdown

◆ suspend