Add the ndiscvt utility from FreeBSD-5, which is used to compile windows
[dragonfly.git] / usr.sbin / ndiscvt / ndiscvt.8
1 .\" Copyright (c) 2003
2 .\"     Bill Paul <wpaul@windriver.com> All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\"    must display the following acknowledgement:
14 .\"     This product includes software developed by Bill Paul.
15 .\" 4. Neither the name of the author nor the names of any co-contributors
16 .\"    may be used to endorse or promote products derived from this software
17 .\"   without specific prior written permission.
18 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY Bill Paul AND CONTRIBUTORS ``AS IS'' AND
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL Bill Paul OR THE VOICES IN HIS HEAD
23 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
29 .\" THE POSSIBILITY OF SUCH DAMAGE.
30 .\"
31 .\" $FreeBSD: src/usr.sbin/ndiscvt/ndiscvt.8,v 1.4 2004/06/13 18:03:42 ru Exp $
32 .\" $DragonFly: src/usr.sbin/ndiscvt/ndiscvt.8,v 1.1 2004/07/30 00:24:24 dillon Exp $
33 .\"
34 .Dd December 10, 2003
35 .Dt NDISCVT 8
36 .Os
37 .Sh NAME
38 .Nm ndiscvt
39 .Nd convert
40 .Tn Windows\[rg]
41 NDIS drivers for use with
42 .Fx
43 .Sh SYNOPSIS
44 .Nm
45 .Op Fl i Ar inffile
46 .Fl s Ar sysfile
47 .Op Fl n Ar devname
48 .Op Fl o Ar outfile
49 .Sh DESCRIPTION
50 The
51 .Nm
52 utility transforms a
53 .Tn Windows\[rg]
54 NDIS driver into a data file which
55 is used to build an
56 .Xr ndis 4
57 compatibility driver module.
58 .Tn Windows\[rg]
59 drivers consist of two main parts: a
60 .Pa .SYS
61 file, which contains the actual driver executable code,
62 and an
63 .Pa .INF
64 file, which provides the
65 .Tn Windows\[rg]
66 installer with device
67 identifier information and a list of driver-specific registry keys.
68 The
69 .Nm
70 utility can convert these files into a header file that is compiled
71 into
72 .Pa if_ndis.c
73 to create an object code module that can be linked into
74 the
75 .Fx
76 kernel.
77 .Pp
78 The
79 .Pa .INF
80 file is typically required since only it contains device
81 identification data such as PCI vendor and device IDs or PCMCIA
82 indentifier strings.
83 The
84 .Pa .INF
85 file may be optionally omitted however,
86 in which case the
87 .Nm
88 utility will only perform the conversion of the
89 .Pa .SYS
90 file.
91 This is useful for debugging purposes only.
92 .Sh OPTIONS
93 The options are as follows:
94 .Bl -tag -width indent
95 .It Fl i Ar inffile
96 Open and parse the specified
97 .Pa .INF
98 file when performing conversion.
99 The
100 .Nm
101 utility will parse this file and emit a device identification
102 structure and registry key configuration structures which will be
103 used by the
104 .Xr ndis 4
105 driver and
106 .Xr ndisapi 9
107 kernel subsystem.
108 If this is omitted,
109 .Nm
110 will emit a dummy configuration structure only.
111 .It Fl s Ar sysfile
112 Open and parse the specified
113 .Pa .SYS
114 file.
115 This file must contain a
116 .Tn Windows\[rg]
117 driver image.
118 The
119 .Nm
120 utility will perform some manipulation of the sections within the
121 executable file to make runtime linking within the kernel a little
122 easier and then convert the image into a data array.
123 .It Fl n Ar devname
124 Specify an alternate name for the network device/interface which will
125 be created when the driver is instantiated.
126 If you need to load more
127 than one NDIS driver into your system (i.e., if you have two different
128 network cards in your system which require NDIS driver support), each
129 module you create must have a unique name.
130 Device can not be larger than
131 .Dv IFNAMSIZ .
132 If no name is specified, the driver will use the
133 default a default name
134 .Pq Dq Li ndis .
135 .It Fl o Ar outfile
136 Specify the output file in which to place the resulting data.
137 This can be any file pathname.
138 If
139 .Ar outfile
140 is a single dash
141 .Pq Sq Fl ,
142 the data will be written to the standard output.
143 The
144 .Pa if_ndis.c
145 module expects to find the driver data in a file called
146 .Pa ndis_driver_data.h ,
147 so it is recommended that this name be used.
148 .El
149 .Sh SEE ALSO
150 .Xr ndis 4 ,
151 .Xr ndisapi 9
152 .Sh HISTORY
153 The
154 .Nm
155 utility first appeared in
156 .Fx 5.3 .
157 .Sh AUTHORS
158 .An -nosplit
159 The
160 .Nm
161 utility was written by
162 .An Bill Paul Aq wpaul@windriver.com .
163 The
164 .Xr lex 1
165 and
166 .Xr yacc 1
167 .Pa INF
168 file parser was written by
169 .An Matthew Dodd Aq mdodd@FreeBSD.org .