180 lines
4.3 KiB
Groff
180 lines
4.3 KiB
Groff
.\" $NetBSD: devsw_attach.9,v 1.3 2017/04/30 12:30:00 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 April 30, 2017
|
|
.Dt DEVSW 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm devsw ,
|
|
.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
|