File:  [DragonFly] / src / share / man / man9 / DEVICE_IDENTIFY.9
Revision 1.2: download - view: text, annotated - select for diffs
Tue Jun 17 04:37:01 2003 UTC (11 years, 2 months ago) by dillon
Branches: MAIN
CVS tags: HEAD
Add the DragonFly cvs id and perform general cleanups on cvs/rcs/sccs ids.  Most
ids have been removed from !lint sections and moved into comment sections.

    1: .\" -*- nroff -*-
    2: .\"
    3: .\" Copyright (c) 2001 Alexander Langer
    4: .\"
    5: .\" All rights reserved.
    6: .\"
    7: .\" This program is free software.
    8: .\"
    9: .\" Redistribution and use in source and binary forms, with or without
   10: .\" modification, are permitted provided that the following conditions
   11: .\" are met:
   12: .\" 1. Redistributions of source code must retain the above copyright
   13: .\"    notice, this list of conditions and the following disclaimer.
   14: .\" 2. Redistributions in binary form must reproduce the above copyright
   15: .\"    notice, this list of conditions and the following disclaimer in the
   16: .\"    documentation and/or other materials provided with the distribution.
   17: .\"
   18: .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
   19: .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   20: .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
   21: .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
   22: .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
   23: .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
   24: .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
   25: .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
   26: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
   27: .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   28: .\"
   29: .\" $FreeBSD: src/share/man/man9/DEVICE_IDENTIFY.9,v 1.2.2.5 2002/03/19 18:24:16 schweikh Exp $
   30: .\" $DragonFly: src/share/man/man9/DEVICE_IDENTIFY.9,v 1.2 2003/06/17 04:37:01 dillon Exp $
   31: .\"
   32: .Dd March 10, 2001
   33: .Dt DEVICE_IDENTIFY 9
   34: .Os
   35: .Sh NAME
   36: .Nm DEVICE_IDENTIFY
   37: .Nd identify a device, register it
   38: .Sh SYNOPSIS
   39: .In sys/param.h
   40: .In sys/bus.h
   41: .Ft void
   42: .Fn DEVICE_IDENTIFY "driver_t *driver" "device_t parent"
   43: .Sh DESCRIPTION
   44: The identify function for a device is only needed for devices on busses
   45: that cannot identify their children independently, e.g. the ISA bus.
   46: It is used to recognize the device (usually done by accessing non-ambigous
   47: registers in the hardware) and to tell the kernel about it and thus
   48: creating a new device instance.
   49: .Pp
   50: .Xr BUS_ADD_CHILD 9
   51: is used to register the device as a child of the bus.
   52: The device's resources (such as IRQ and I/O ports) are registered
   53: with the kernel by calling
   54: .Fn bus_set_resource
   55: for each resource (refer to
   56: .Xr bus_set_resource 9
   57: for more information).
   58: .Sh EXAMPLES
   59: The following pseudo-code shows an example of a function that
   60: probes for a piece of hardware and registers it and its resource
   61: (an I/O port) with the kernel.
   62: It also sets the description of the device.
   63: .Bd -literal
   64: void
   65: foo_identify(driver_t *driver, device_t parent)
   66: {
   67: 	device_t child;
   68: 
   69: 	retrieve_device_information;
   70: 	if (devices matches one of your supported devices) {
   71: 		child = BUS_ADD_CHILD(parent, 0, "foo", -1);
   72: 		device_set_desc_copy(child, "foo chip ver.123");
   73: 		device_set_driver(child, driver);
   74: 		bus_set_resource(child, SYS_RES_IOPORT, 0, FOO_IOADDR, 1);
   75: 	}
   76: }
   77: .Ed
   78: .Sh RETURN VALUES
   79: Zero is returned on success,
   80: otherwise an appropriate error is returned (see
   81: .Xr errno 2 ) .
   82: .Sh SEE ALSO
   83: .Xr BUS_ADD_CHILD 9 ,
   84: .Xr bus_set_resource 9 ,
   85: .Xr device 9 ,
   86: .Xr device_add_child 9 ,
   87: .Xr DEVICE_ATTACH 9 ,
   88: .Xr DEVICE_DETACH 9 ,
   89: .Xr DEVICE_PROBE 9 ,
   90: .Xr device_set_desc_copy 9 ,
   91: .Xr device_set_driver 9 ,
   92: .Xr DEVICE_SHUTDOWN 9
   93: .Sh AUTHORS
   94: This man page was written by
   95: .An Alexander Langer Aq alex@FreeBSD.org .