From owner-svn-src-all@FreeBSD.ORG Tue May 24 13:22:41 2011 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 0122A1065677; Tue, 24 May 2011 13:22:41 +0000 (UTC) (envelope-from jhb@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id CD2868FC08; Tue, 24 May 2011 13:22:40 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id p4ODMeR7070086; Tue, 24 May 2011 13:22:40 GMT (envelope-from jhb@svn.freebsd.org) Received: (from jhb@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id p4ODMejk070084; Tue, 24 May 2011 13:22:40 GMT (envelope-from jhb@svn.freebsd.org) Message-Id: <201105241322.p4ODMejk070084@svn.freebsd.org> From: John Baldwin Date: Tue, 24 May 2011 13:22:40 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r222253 - head/sys/kern X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 24 May 2011 13:22:41 -0000 Author: jhb Date: Tue May 24 13:22:40 2011 New Revision: 222253 URL: http://svn.freebsd.org/changeset/base/222253 Log: Update comments for DEVICE_PROBE() to reflect that BUS_PROBE_DEFAULT is now the preferred typical return value from a probe routine. Discourage the use of 0 (BUS_PROBE_SPECIFIC) as it should be used very rarely. Point the reader to the DEVICE_PROBE(9) manpage for more detailed notes on possible probe return values. Submitted by: Philip Soeberg philip-dev of soeberg net Modified: head/sys/kern/device_if.m Modified: head/sys/kern/device_if.m ============================================================================== --- head/sys/kern/device_if.m Tue May 24 13:17:08 2011 (r222252) +++ head/sys/kern/device_if.m Tue May 24 13:22:40 2011 (r222253) @@ -89,28 +89,29 @@ CODE { * 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. + * 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. + * 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. + * immediately. This should rarely be used. * - * For example, a probe method for a pci device driver might look + * For example, a probe method for a PCI device driver might look * like this: * * @code - * int foo_probe(device_t dev) + * int + * foo_probe(device_t dev) * { * if (pci_get_vendor(dev) == FOOVENDOR && * pci_get_device(dev) == FOODEVICE) { * device_set_desc(dev, "Foo device"); - * return (0); + * return (BUS_PROBE_DEFAULT); * } * return (ENXIO); * } @@ -125,7 +126,8 @@ CODE { * * @param dev the device to probe * - * @retval 0 if the driver strongly matches this device + * @retval 0 if this is the only possible driver for this + * device * @retval negative if the driver can match this device - the * least negative value is used to select the * driver