Write the Probe Function

The purpose of the bus probe routine is to detect devices residing on the bus and to create device nodes corresponding to these devices. The probe routine is optional. In case it is not provided (NULL entry point), a device node should be statically created at boot time, or should be created by another "probe only" driver component to activate the bus driver.

Actions taken by a probe routine may be summarized as follows:

• The probe routine creates nodes if, and only if, they do not already exist. In other words, the probe routine is forbidden to create redundant nodes.

• The probe routine specifies a physical device ID as a device node property so that the bus driver can find the appropriate device driver for this device node.

  Note that the device ID is bus class specific. For instance, on a PCI bus, the device ID is the vendor/device IDs pair.

• The probe routine specifies resource requirements as device node properties so that the bus driver can reserve resources required to initialize the device.

There are two kinds of probe routines:

• generic (bus class specific only)

  A self-identifying bus (such as PCI) enumerator is a typical example of the generic probe routine.

• device specific (bus class and device specific)

  A device probing code on ISA bus is a typical example of the device specific probe routine.

Note that multiple probe routines for a given bus may be found in the driver registry. The Driver Framework does not specify the order in which the probe routines will be run. In addition, the probe routines may be invoked at run time (when, for example, the device insertion is detected on the bus).

When invoked at runtime, the probe routines must exercise extreme care with regard to active device nodes. Active device nodes are those for which the device drivers have been already started and may already be in use.

The following rules must be respected by generic and device specific probe routines:

• The generic and specific probe routines must access the device hardware only through the bus service routines. The bus resources needed to access the device hardware (such as I/O registers) must be allocated through the bus service routines (resource_alloc). This prevents the probe routine from accessing hardware which is currently in use. Upon unsuccessful probing, the hardware resources used must be released through the bus service routines (resource_free).

• Neither generic nor specific probe routines are allowed to delete active device nodes or to modify their properties. (Such nodes are flagged with the active property.)

• Device specific probe routines are allowed to override properties in an existing node or to delete existing nodes.

• Generic probe routines are not allowed to override properties in existing nodes or to delete existing nodes. In other words, device specific probe routines have a higher priority than generic ones.

• No probe routine is allowed to create redundant nodes. To run a probe routine, either you must be positive that no other node exists for this device, or you must be able to find any other nodes for this device. If for some reason it is impossible to avoid creating redundant nodes, you cannot probe.