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.9 2006/10/10 07:19:30 trhodes Exp $
  32 .\"
  33 .Dd May 10, 2011
  34 .Dt NDISCVT 8
  35 .Os
  36 .Sh NAME
  37 .Nm ndiscvt
  38 .Nd convert
  39 .Tn Windows\[rg]
  40 NDIS drivers for use with DragonFly
  41 .Sh SYNOPSIS
  42 .Nm
  43 .Op Fl O
  44 .Op Fl i Ar inffile
  45 .Fl s Ar sysfile
  46 .Op Fl n Ar devname
  47 .Op Fl o Ar outfile
  48 .Nm
  49 .Op Fl f Ar firmfile
  50 .Sh DESCRIPTION
  51 The
  52 .Nm
  53 utility transforms a
  54 .Tn Windows\[rg]
  55 NDIS driver into a data file which
  56 is used to build an
  57 .Xr ndis 4
  58 compatibility driver module.
  59 .Tn Windows\[rg]
  60 drivers consist of two main parts: a
  61 .Pa .SYS
  62 file, which contains the actual driver executable code,
  63 and an
  64 .Pa .INF
  65 file, which provides the
  66 .Tn Windows\[rg]
  67 installer with device
  68 identifier information and a list of driver-specific registry keys.
  69 The
  70 .Nm
  71 utility can convert these files into a header file that is compiled
  72 into
  73 .Pa if_ndis.c
  74 to create an object code module that can be linked into
  75 the
  76 .Dx
  77 kernel.
  78 .Pp
  79 The
  80 .Pa .INF
  81 file is typically required since only it contains device
  82 identification data such as PCI vendor and device IDs or PCMCIA
  83 identifier strings.
  84 The
  85 .Pa .INF
  86 file may be optionally omitted however,
  87 in which case the
  88 .Nm
  89 utility will only perform the conversion of the
  90 .Pa .SYS
  91 file.
  92 This is useful for debugging purposes only.
  93 .Sh OPTIONS
  94 The options are as follows:
  95 .Bl -tag -width indent
  96 .It Fl i Ar inffile
  97 Open and parse the specified
  98 .Pa .INF
  99 file when performing conversion.
 100 The
 101 .Nm
 102 utility will parse this file and emit a device identification
 103 structure and registry key configuration structures which will be
 104 used by the
 105 .Xr ndis 4
 106 driver and
 107 .Nm ndisapi
 108 kernel subsystem.
 109 If this is omitted,
 110 .Nm
 111 will emit a dummy configuration structure only.
 112 .It Fl s Ar sysfile
 113 Open and parse the specified
 114 .Pa .SYS
 115 file.
 116 This file must contain a
 117 .Tn Windows\[rg]
 118 driver image.
 119 The
 120 .Nm
 121 utility will perform some manipulation of the sections within the
 122 executable file to make runtime linking within the kernel a little
 123 easier and then convert the image into a data array.
 124 .It Fl n Ar devname
 125 Specify an alternate name for the network device/interface which will
 126 be created when the driver is instantiated.
 127 If you need to load more
 128 than one NDIS driver into your system (i.e., if you have two different
 129 network cards in your system which require NDIS driver support), each
 130 module you create must have a unique name.
 131 Device can not be larger than
 132 .Dv IFNAMSIZ .
 133 If no name is specified, the driver will use the
 134 default a default name
 135 .Pq Dq Li ndis .
 136 .It Fl o Ar outfile
 137 Specify the output file in which to place the resulting data.
 138 This can be any file pathname.
 139 If
 140 .Ar outfile
 141 is a single dash
 142 .Pq Sq Fl ,
 143 the data will be written to the standard output.
 144 The
 145 .Pa if_ndis.c
 146 module expects to find the driver data in a file called
 147 .Pa ndis_driver_data.h ,
 148 so it is recommended that this name be used.
 149 .It Fl O
 150 Generate both an
 151 .Pa ndis_driver_data.h
 152 file and
 153 an
 154 .Pa ndis_driver.data.o
 155 file.
 156 The latter file will contain a copy of the
 157 .Tn Windows\[rg]
 158 .Pa .SYS
 159 driver image encoded as a
 160 .Dx
 161 ELF object file
 162 (created with
 163 .Xr objcopy 1 ) .
 164 Turning the
 165 .Tn Windows\[rg]
 166 driver image directly into an object code file saves disk space
 167 and compilation time.
 168 .It Fl f Ar firmfile
 169 A few NDIS drivers come with additional files that the core
 170 driver module will load during initialization time.
 171 Typically,
 172 these files contain firmware which the driver will transfer to
 173 the device in order to make it fully operational.
 174 In
 175 .Tn Windows\[rg] ,
 176 these files are usually just copied into one of the system
 177 directories along with the driver itself.
 178 .Pp
 179 In
 180 .Dx
 181 there are two mechanism for loading these files.
 182 If the driver
 183 is built as a loadable kernel module which is loaded after the
 184 kernel has finished booting
 185 (and after the root file system has
 186 been mounted),
 187 the extra files can simply be copied to the
 188 .Pa /compat/ndis
 189 directory, and they will be loaded into the kernel on demand when the
 190 the driver needs them.
 191 .Pp
 192 If however the driver is required to bootstrap the system
 193 (i.e., if
 194 the NDIS-based network interface is to be used for diskless/PXE
 195 booting),
 196 the files need to be pre-loaded by the bootstrap
 197 loader in order to be accessible, since the driver will need them
 198 before the root file system has been mounted.
 199 However, the bootstrap
 200 loader is only able to load files that are shared
 201 .Dx
 202 binary objects.
 203 .Pp
 204 The
 205 .Fl f
 206 flag can be used to convert an arbitrary file
 207 .Ar firmfile
 208 into shared object format
 209 (the actual conversion is done using
 210 the
 211 .Xr objcopy 1
 212 and
 213 .Xr ld 1
 214 commands).
 215 The resulting files can then be copied to the
 216 .Pa /boot/kernel
 217 directory, and can be pre-loaded directly from the boot loader
 218 prompt, or automatically by editing the
 219 .Xr loader.conf 5
 220 file.
 221 If desired, the files can also be loaded into memory
 222 at runtime using the
 223 .Xr kldload 8
 224 command.
 225 .Pp
 226 When an NDIS driver tries to open an external file, the
 227 .Nm ndisapi
 228 code will first search for a loaded kernel module that matches the
 229 name specified in the open request, and if that fails, it will then
 230 try to open the file from the
 231 .Pa /compat/ndis
 232 directory as well.
 233 Note that during kernel bootstrap, the ability
 234 to open files from
 235 .Pa /compat/ndis
 236 is disabled: only the module search will be performed.
 237 .Pp
 238 When using the
 239 .Fl f
 240 flag,
 241 .Nm
 242 will generate both a relocatable object file
 243 (with a
 244 .Pa .o
 245 extension)
 246 and a shared object file
 247 (with a
 248 .Pa .ko
 249 extension).
 250 The shared object is the one that should be placed in
 251 the
 252 .Pa /boot/kernel
 253 directory.
 254 The relocatable object file is useful if the user wishes
 255 to create a completely static kernel image: the object file can be
 256 linked into the kernel directly along with the driver itself.
 257 Some
 258 editing of the kernel configuration files will be necessary in order
 259 to have the extra object included in the build.
 260 .El
 261 .Sh SEE ALSO
 262 .Xr ld 1 ,
 263 .Xr objcopy 1 ,
 264 .Xr ndis 4 ,
 265 .Xr kldload 8
 266 .Sh HISTORY
 267 The
 268 .Nm
 269 utility first appeared in
 270 .Fx 5.3 .
 271 .Sh AUTHORS
 272 .An -nosplit
 273 The
 274 .Nm
 275 utility was written by
 276 .An Bill Paul Aq wpaul@windriver.com .
 277 The
 278 .Xr lex 1
 279 and
 280 .Xr yacc 1
 281 .Pa INF
 282 file parser was written by
 283 .An Matthew Dodd Aq mdodd@FreeBSD.org .