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.3 2008/07/26 18:37:43 swildner 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 .Dx
  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 .Dx
  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 .Nm ndisapi
 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 .Sh HISTORY
 152 The
 153 .Nm
 154 utility first appeared in
 155 .Fx 5.3 .
 156 .Sh AUTHORS
 157 .An -nosplit
 158 The
 159 .Nm
 160 utility was written by
 161 .An Bill Paul Aq wpaul@windriver.com .
 162 The
 163 .Xr lex 1
 164 and
 165 .Xr yacc 1
 166 .Pa INF
 167 file parser was written by
 168 .An Matthew Dodd Aq mdodd@FreeBSD.org .