File:  [DragonFly] / src / share / man / man9 / DEVICE_IDENTIFY.9
Revision 1.3: download - view: text, annotated - select for diffs
Tue Jun 1 11:36:53 2004 UTC (10 years, 5 months ago) by hmp
Branches: MAIN
CVS tags: HEAD, DragonFly_Stable, DragonFly_Snap29Sep2004, DragonFly_Snap13Sep2004, DragonFly_RELEASE_1_4_Slip, DragonFly_RELEASE_1_4, DragonFly_RELEASE_1_2_Slip, DragonFly_RELEASE_1_2, DragonFly_1_0_REL, DragonFly_1_0_RC1, DragonFly_1_0A_REL
Remove '-*- nroff -*-'.

Lets make a habit not to put editor-related magic into our base
files.  They are redundant and useless.

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