[src/trunk]: src/share/man/man9 Add new man page for devsw_attach() and friends.

[pgoyette <pgoyette%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/dcb277acfd0c
branches:  trunk
changeset: 338195:dcb277acfd0c
user:      pgoyette <pgoyette%NetBSD.org@localhost>
date:      Thu May 14 00:08:44 2015 +0000

description:
Add new man page for devsw_attach() and friends.

>From Kamil Ritarowski with some editting by myself.

diffstat:

 share/man/man9/Makefile       |    9 +-
 share/man/man9/devsw_attach.9 |  178 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 185 insertions(+), 2 deletions(-)

diffs (212 lines):

diff -r c024df12ef14 -r dcb277acfd0c share/man/man9/Makefile
--- a/share/man/man9/Makefile   Thu May 14 00:07:04 2015 +0000
+++ b/share/man/man9/Makefile   Thu May 14 00:08:44 2015 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.386 2015/04/27 07:03:57 knakahara Exp $
+#       $NetBSD: Makefile,v 1.387 2015/05/14 00:08:44 pgoyette Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -16,7 +16,7 @@
        cpu_startup.9 cpu_switchto.9 cpufreq.9 \
        csf.9 ctod.9 \
        curproc.9 \
-       delay.9 disk.9 ddc.9 disklabel.9 dofileread.9 \
+       delay.9 devsw_attach.9 disk.9 ddc.9 disklabel.9 dofileread.9 \
        dopowerhooks.9 do_setresuid.9 doshutdownhooks.9 driver.9 \
        edid.9 errno.9 ethersubr.9 evcnt.9 extattr.9 extent.9 \
        fetch.9 file.9 fileassoc.9 filedesc.9 firmload.9 flash.9 \
@@ -278,6 +278,11 @@
        ctod.9 btodb.9
 MLINKS+=curproc.9 curcpu.9 curproc.9 curlwp.9
 MLINKS+=delay.9 DELAY.9
+MLINKS+=devsw_attach.9 devsw_detach.9 \
+       devsw_attach.9 bdevsw_lookup.9 \
+       devsw_attach.9 cdevsw_lookup.9 \
+       devsw_attach.9 bdevsw_lookup_major.9 \
+       devsw_attach.9 cdevsw_lookup_major.9
 MLINKS+=disk.9 disk_attach.9 disk.9 disk_detach.9 \
        disk.9 disk_busy.9 disk.9 disk_unbusy.9 disk.9 disk_find.9 \
        disk.9 disk_init.9 disk.9 disk_destroy.9 disk.9 disk_begindetach.9
diff -r c024df12ef14 -r dcb277acfd0c share/man/man9/devsw_attach.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/devsw_attach.9     Thu May 14 00:08:44 2015 +0000
@@ -0,0 +1,178 @@
+.\"    $NetBSD: devsw_attach.9,v 1.1 2015/05/14 00:08:44 pgoyette Exp $
+.\"
+.\" Copyright (c) 2015 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Kamil Rytarowski.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd May 13, 2015
+.Dt DEVSW_ATTACH 9
+.Os
+.Sh NAME
+.Nm devsw_attach ,
+.Nm devsw_detach ,
+.Nm bdevsw_lookup ,
+.Nm cdevsw_lookup ,
+.Nm bdevsw_lookup_major ,
+.Nm cdevsw_lookup_major
+.Nd character and block device switch functions
+.Sh SYNOPSIS
+.In sys/conf.h
+.Ft int
+.Fo devsw_attach
+.Fa "const char *devname"
+.Fa "const struct bdevsw *bev"
+.Fa "devmajor_t *bmajor"
+.Fa "const struct cdevsw *cdev"
+.Fa "devmajor_t *cmajor"
+.Fc
+.Ft int
+.Fo devsw_detach
+.Fa "const struct bdevsw *bdev"
+.Fa "const struct cdevsw *cdev"
+.Fc
+.Ft "const struct bdevsw *"
+.Fo bdevsw_lookup
+.Fa "dev_t dev"
+.Fc
+.Ft "const struct cdevsw *"
+.Fo cdevsw_lookup
+.Fa "dev_t dev"
+.Fc
+.Ft devmajor_t
+.Fo bdevsw_lookup_major
+.Fa "const struct bdevsw *bdev"
+.Fc
+.Ft devmajor_t
+.Fo cdevsw_lookup_major
+.Fa "const struct cdevsw *cdev"
+.Fc
+.Sh DESCRIPTION
+If a device driver has character device interfaces accessed from
+userland, the driver must define a
+.Em cdevsw
+structure.
+If the driver also has block device interfaces, the driver must
+additionally define a
+.Em bdevsw
+structure.
+These structures are constant, and are defined within the
+.Xr driver 9 .
+.Pp
+For drivers which are included in the kernel via
+.Xr config 1 ,
+the
+.Em cdevsw
+and
+.Em bdevsw
+structures are automatically linked into the configuration database.
+For drivers which are separately loaded, the
+.Fn devsw_attach
+function creates the necessary linkage and associates the
+.Em cdev
+and optional
+.Em bdev
+with the
+.Xr driver 9 .
+If there is no block device interface needed,
+.Em bdev
+should be set to
+.Dv NULL
+and
+.Em bmajor
+to
+.Dv -1 .
+The
+.Em devname ,
+major number, and device type
+(character or block)
+must correspond to the device file which will be opened by user programs.
+By passing
+.Dv -1
+to the function for the
+.Em cmajor
+or
+.Em bmajor ,
+the major number can be automatically generated.
+It can then be returned to userspace (for example, using
+.Xr sysctl 8 )
+for creation of the device node.
+.Pp
+The
+.Fn devsw_detach
+function is used to detach the
+.Em bdev
+and
+.Em cdev
+structures.
+.Fn devsw_detach
+should be called before a loaded device driver is unloaded.
+.Pp
+The
+.Fn bdevsw_lookup
+and
+.Fn cdevsw_lookup
+functions return
+.Em "const struct bdevsw *"
+and
+.Em "const struct cdevsw *"
+for the given
+.Em dev .
+.Pp
+The
+.Fn bdevsw_lookup_major
+and
+.Fn cdevsw_lookup_major
+functions return
+.Em "devmajor_t"
+for the given
+.Em "const struct bdevsw *"
+or
+.Em "const struct cdevsw *" .
+.Sh RETURN VALUES
+Upon successful completion,
+.Fn devsw_attach
+and
+.Fn devsw_detach
+return 0.
+Otherwise they return an error value.
+.Pp
+In case of failure,
+.Fn bdevsw_lookup
+and
+.Fn cdevsw_lookup
+return the
+.Dv NULL
+value.
+.Pp
+The
+.Fn bdevsw_lookup_major
+and
+.Fn cdevsw_lookup_major
+functions return
+.Dv NODEVMAJOR
+for an unsuccessful completion.
+.Sh SEE ALSO
+.Xr driver 9