2 .\" Bill Paul <wpaul@windriver.com> All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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.
40 NDIS drivers for use with FreeBSD
55 NDIS driver into a data file which
58 compatibility driver module.
60 drivers consist of two main parts: a
62 file, which contains the actual driver executable code,
65 file, which provides the
68 identifier information and a list of driver-specific registry keys.
71 utility can convert these files into a header file that is compiled
74 to create an object code module that can be linked into
81 file is typically required since only it contains device
82 identification data such as PCI vendor and device IDs or PCMCIA
86 file may be optionally omitted however,
89 utility will only perform the conversion of the
92 This is useful for debugging purposes only.
94 The options are as follows:
95 .Bl -tag -width indent
97 Open and parse the specified
99 file when performing conversion.
102 utility will parse this file and emit a device identification
103 structure and registry key configuration structures which will be
111 will emit a dummy configuration structure only.
113 Open and parse the specified
116 This file must contain a
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.
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
133 If no name is specified, the driver will use the
134 default a default name
137 Specify the output file in which to place the resulting data.
138 This can be any file pathname.
143 the data will be written to the standard output.
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.
151 .Pa ndis_driver_data.h
154 .Pa ndis_driver.data.o
156 The latter file will contain a copy of the
159 driver image encoded as a
166 driver image directly into an object code file saves disk space
167 and compilation time.
169 A few NDIS drivers come with additional files that the core
170 driver module will load during initialization time.
172 these files contain firmware which the driver will transfer to
173 the device in order to make it fully operational.
176 these files are usually just copied into one of the system
177 directories along with the driver itself.
181 there are two mechanism for loading these files.
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
187 the extra files can simply be copied to the
189 directory, and they will be loaded into the kernel on demand when the
190 the driver needs them.
192 If however the driver is required to bootstrap the system
194 the NDIS-based network interface is to be used for diskless/PXE
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
206 flag can be used to convert an arbitrary file
208 into shared object format
209 (the actual conversion is done using
215 The resulting files can then be copied to the
217 directory, and can be pre-loaded directly from the boot loader
218 prompt, or automatically by editing the
221 If desired, the files can also be loaded into memory
226 When an NDIS driver tries to open an external file, the
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
233 Note that during kernel bootstrap, the ability
236 is disabled: only the module search will be performed.
242 will generate both a relocatable object file
246 and a shared object file
250 The shared object is the one that should be placed in
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.
258 editing of the kernel configuration files will be necessary in order
259 to have the extra object included in the build.
270 utility first appeared in
276 utility was written by
277 .An Bill Paul Aq wpaul@windriver.com .
283 file parser was written by
284 .An Matthew Dodd Aq mdodd@FreeBSD.org .