NetBSD/share/man/man4/man4.i386/ndis.4

.\" $NetBSD: ndis.4,v 1.5 2014/03/18 18:20:40 riastradh Exp $
.\"
.\" Copyright (c) 2003
.\"     Bill Paul <wpaul@windriver.com>. All rights reserved.
.\"
.\" 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.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"     This product includes software developed by Bill Paul.
.\" 4. Neither the name of the author nor the names of any co-contributors
.\"    may be used to endorse or promote products derived from this software
.\"   without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD
.\" 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.
.\"
.\" $FreeBSD: /repoman/r/ncvs/src/share/man/man4/man4.i386/ndis.4,v 1.7.2.1 2004/12/24 22:24:04 brueffer Exp $
.\"
.Dd December 10, 2003
.Dt NDIS 4 i386
.Os
.Sh NAME
.Nm ndis
.Nd NDIS miniport driver wrapper
.Sh SYNOPSIS
.Cd "ndis* at pci? dev ? function ?"
.Sh DESCRIPTION
The
.Nm
wrapper is designed to allow binary
.Tn Windows\[rg]
NDIS miniport
network drivers to be used with
.Nx .
The
.Nm
driver is provided in source code form
.Pq Pa sys/dev/if_ndis
and must be combined with the
.Tn Windows\[rg]
driver binary supplied with your network adapter.
The
.Nm
driver uses the
.\".Xr ndisapi 9
ndisapi
kernel subsystem to relocate and link the
.Tn Windows\[rg]
binary so
that it can be used in conjunction with native code.
The
.\".Xr ndisapi 9
ndisapi
subsystem provides an interface between the NDIS API and the
.Nx
networking infrastructure.
The
.Tn Windows\[rg]
driver is essentially
fooled into thinking it is running on
.Tn Windows\[rg] .
Note that this
means the
.Nm
driver is only useful on x86 machines.
.Pp
To build a functional driver, the user must have a copy of the
driver distribution media for his or her card.
From this distribution,
the user must extract two files: the
.Pa .SYS
file containing the driver
binary code, and its companion
.Pa .INF
file, which contains the
definitions for driver-specific registry keys and other installation
data such as device identifiers.
These two files are converted
into a
.Pa ndis_driver_data.h
file using the
.Xr ndiscvt 8
utility.
The resulting file contains a binary image of the driver plus
registry key data.
The
.Pa ndis_driver_data.h
is included in several files located in
.Pa sys/dev/if_ndis
so it is needed to compile an NDIS kernel.
When the
.Nm
driver is loaded, it will create
.Xr sysctl 3
nodes for each registry key extracted from the
.Pa .INF
file.
.Pp
The
.Nm
wrapper is designed to support mainly Ethernet and wireless
network devices/drivers with PCI bus attachments.
It can
support many different media types and speeds.
.Pp
One limitation
however, is that there is no consistent way to learn if an
Ethernet device is operating in full or half duplex mode.
The NDIS API allows for a generic means for determining link
state and speed, but not the duplex setting.
There may be
driver-specific registry keys to control the media setting
which can be configured via the
.Xr sysctl 8
command.
.Sh EXAMPLES
Assuming you have obtained the appropriate
.Pa .INF
and
.Pa .SYS
files for your device, the
.Pa ndis_driver_data.h
file can be built as follows:
.Bd -literal -offset indent
$ ndiscvt -i your_card.INF -s your_card.SYS -o ndis_driver_data.h
.Ed
.Pp
Next uncomment the following lines from
.Pa sys/arch/i386/conf/GENERIC
.Bd -literal -offset indent
$ cd /usr/src/sys/arch/i386/conf
$ cp GENERIC NDIS
$ vi NDIS
 .
 .
 .
options         COMPAT_NDIS # NDIS network driver
 .
 .
 .
ndis*   at pci? dev ? function ? # Experimental - NDIS Network Driver
.Ed
.Pp
Configure your kernel, then copy the
.Pa ndis_driver_data.h
file into the kernel build directory before compiling the kernel:
.Bd -literal -offset indent
$ cd src/sys/arch/i386/conf
$ config NDIS
$ cd ../compile/NDIS
$ cp /path/to/ndis_driver_data.h .
$ make depend \*[Am]\*[Am] make
$ su
$ mv /netbsd /onetbsd
$ cp netbsd /netbsd
$ reboot
.Ed
.Pp
The ndis0 device should be detected at boot:
.Bd -literal -offset indent
Matching vendor: 14e4, product: 4324, name: Dell TrueMobile 1400 Dual Band WLAN Mini-PCI Card
ndis0 at pci2 dev 3 function 0
.Ed
.Pp
The device can then be configured with
.Xr ifconfig 8 :
.Pp
.Bd -literal -offset indent
ndis0: flags=8843\*[Lt]UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST\*[Gt] mtu 1500
        ssid WWUwireless
        powersave on (100ms sleep)
        chan 6
        address: 00:90:4b:69:94:f0
        media: IEEE802.11 autoselect
        status: no network
        inet 140.160.129.226 netmask 0xfffffc00 broadcast 140.160.131.255
        inet6 fe80::290:4bff:fe69:94f0%ndis0 prefixlen 64 scopeid 0x3
.Ed
.Pp
If the
.Nm
driver creates any sysctl nodes, they can be viewed and altered with
.Xr sysctl 8 :
.Bd -literal -offset indent
$ sysctl ndis0
 .
 .
 .
ndis0.ndis_10280001 = Dell TrueMobile 1300 WLAN Mini-PCI Card
ndis0.ndis_Environment = 1
ndis0.ndis_NdisVersion = 0x00050001
ndis0.ndis_BusType = 5
 .
 .
 .
.Ed
.Sh DIAGNOSTICS
.Bl -diag
.It "ndis%d: watchdog timeout"
A packet was queued for transmission and a transmit command was
issued, however the device failed to acknowledge the transmission
before a timeout expired.
.El
.Sh SEE ALSO
.Xr arp 4 ,
.Xr netintro 4 ,
.\".Xr ng_ether 4 ,
.Xr ifconfig 8 ,
.Xr ndiscvt 8
.\".Xr ndisapi 9
.Rs
.%T "NDIS 5.1 specification"
.%U http://www.microsoft.com
.Re
.Sh HISTORY
The
.Nm
driver wrapper first appeared in
.Fx 5.3
and was ported to
.Nx 4.0 .
.Sh AUTHORS
The
.Nm
driver was written by
.An Bill Paul Aq Mt wpaul@windriver.com .
It was ported to
.Nx
by
.An Alan Ritter Aq Mt rittera@NetBSD.org
with help from
.An Phil Nelson Aq Mt phil@NetBSD.org
as part of Google's Summer of Code 2005.