Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DEVICE_PROBE(9)		 BSD Kernel Developer's	Manual	       DEVICE_PROBE(9)

     DEVICE_PROBE -- probe for device existence

     #include <sys/param.h>
     #include <sys/bus.h>

     DEVICE_PROBE(device_t dev);

     The DEVICE_PROBE()	method should probe to see if the device is present.
     It	should return 0	if the device exists, ENXIO if it cannot be found.  If
     some other	error happens during the probe (such as	a memory allocation
     failure), an appropriate error code should	be returned.  For cases	where
     more than one driver matches a device, a priority value can be returned.
     In	this case, success codes are values less than or equal to zero with
     the highest value representing the	best match.  Failure codes are repre-
     sented by positive	values and the regular UNIX error codes	should be used
     for the purpose.

     If	a driver returns a success code	which is less than zero, it must not
     assume that it will be the	same driver which is attached to the device.
     In	particular, it must not	assume that any	values stored in the softc
     structure will be available for its attach	method and any resources allo-
     cated during probe	must be	released and re-allocated if the attach	method
     is	called.	 In addition it	is an absolute requirement that	the probe rou-
     tine have no side effects whatsoever.  The	probe routine may be called
     more than once before the attach routine is called.

     If	a success code of zero is returned, the	driver can assume that it will
     be	the one	attached, but must not hold any	resources when the probe rou-
     tine returns.  A driver may assume	that the softc is preserved when it
     returns a success code of zero.

     A value equal to or less than zero	indicates success, greater than	zero
     indicates an error	(errno).  For values equal to or less than zero: zero
     indicates highest priority, no further probing is done; for a value less
     than zero,	the lower the value the	lower the priority, e.g. -100 indi-
     cates a lower priority than -50.

     The following values are used by convention to indicate different
     strengths of matching in a	probe routine.	Except as noted, these are
     just suggested values, and	there's	nothing	magical	about them.

     BUS_PROBE_SPECIFIC	   The device that cannot be reprobed, and that	no
			   possible other driver may exist (typically legacy
			   drivers who don't follow all	the rules, or special
			   needs drivers).

     BUS_PROBE_VENDOR	   The device is supported by a	vendor driver.	This
			   is for source or binary drivers that	are not	yet
			   integrated into the FreeBSD tree.  Its use in the
			   base	OS is prohibited.

     BUS_PROBE_DEFAULT	   The device is a normal device matching some plug
			   and play ID.	 This is the normal return value for
			   drivers to use.  It is intended that	nearly all of
			   the drivers in the tree should return this value.

			   The driver is a legacy driver, or an	otherwise less
			   desirable driver for	a given	plug and play ID.  The
			   driver has special requirements like	when there are
			   two drivers that support overlapping	series of
			   hardware devices.  In this case the one that	sup-
			   ports the older part	of the line would return this
			   value, while	the one	that supports the newer	ones
			   would return	BUS_PROBE_DEFAULT.

     BUS_PROBE_GENERIC	   The driver matches the type of device generally.
			   This	allows drivers to match	all serial ports gen-
			   erally, with	specialized drivers matching particu-
			   lar types of	serial ports that need special treat-
			   ment	for some reason.

     BUS_PROBE_HOOVER	   The driver matches all unclaimed devices on a bus.
			   The ugen(4) device is one example.

     BUS_PROBE_NOWILDCARD  The driver expects its parent to tell it which
			   children to manage and no probing is	really done.
			   The device only matches if its parent bus specifi-
			   cally said to use this driver.


     This manual page was written by Doug Rabson.

BSD			       February	8, 2012				   BSD


Want to link to this manual page? Use this URL:

home | help