ndiscvt(8)
NAME
- ndiscvt - convert Windows(R) NDIS drivers for use with
- FreeBSD
SYNOPSIS
ndiscvt [-O] [-i inffile] -s sysfile [-n devname] [-o
outfile]
ndiscvt [-f firmfile]
DESCRIPTION
- The ndiscvt utility transforms a Windows(R) NDIS driver into
- a data file
which is used to build an ndis(4) compatibility driver mod - ule.
Windows(R) drivers consist of two main parts: a .SYS file, - which contains
the actual driver executable code, and an .INF file, which - provides the
Windows(R) installer with device identifier information and - a list of
driver-specific registry keys. The ndiscvt utility can con - vert these
files into a header file that is compiled into if_ndis.c to - create an
object code module that can be linked into the FreeBSD ker - nel.
- The .INF file is typically required since only it contains
- device identification data such as PCI vendor and device IDs or PCMCIA
- identifier
strings. The .INF file may be optionally omitted however, - in which case
the ndiscvt utility will only perform the conversion of the - .SYS file.
This is useful for debugging purposes only.
OPTIONS
The options are as follows:
- -i inffile
- Open and parse the specified .INF file when perform
- ing conversion. The ndiscvt utility will parse this file and
- emit a device
identification structure and registry key configura - tion structures which will be used by the ndis(4) driver and
- ndisapi(9)
kernel subsystem. If this is omitted, ndiscvt will - emit a dummy
configuration structure only. - -s sysfile
- Open and parse the specified .SYS file. This file
- must contain a
Windows(R) driver image. The ndiscvt utility will - perform some
manipulation of the sections within the executable - file to make
runtime linking within the kernel a little easier - and then convert the image into a data array.
- -n devname
- Specify an alternate name for the network device/in
- terface which
will be created when the driver is instantiated. If - you need to
load more than one NDIS driver into your system - (i.e., if you
have two different network cards in your system - which require
NDIS driver support), each module you create must - have a unique
name. Device can not be larger than IFNAMSIZ. If - no name is
specified, the driver will use the default a default - name
(``ndis''). - -o outfile
- Specify the output file in which to place the re
- sulting data.
This can be any file pathname. If outfile is a sin - gle dash
(`-'), the data will be written to the standard out - put. The
if_ndis.c module expects to find the driver data in - a file called
ndis_driver_data.h, so it is recommended that this - name be used.
- -O Generate both an ndis_driver_data.h file and an
- ndis_driver.data.o file. The latter file will con
- tain a copy of
the Windows(R) .SYS driver image encoded as a FreeB - SD ELF object
file (created with objcopy(1)). Turning the Win - dows(R) driver
image directly into an object code file saves disk - space and compilation time.
- -f firmfile
- A few NDIS drivers come with additional files that
- the core
driver module will load during initialization time. - Typically,
these files contain firmware which the driver will - transfer to
the device in order to make it fully operational. - In Windows(R),
these files are usually just copied into one of the - system directories along with the driver itself.
- In FreeBSD there are two mechanism for loading these
- files. If
the driver is built as a loadable kernel module - which is loaded
after the kernel has finished booting (and after the - root file
system has been mounted), the extra files can simply - be copied to
the /compat/ndis directory, and they will be loaded - into the kernel on demand when the the driver needs them.
- If however the driver is required to bootstrap the
- system (i.e.,
if the NDIS-based network interface is to be used - for diskless/PXE booting), the files need to be pre-loaded
- by the bootstrap loader in order to be accessible, since the
- driver will
need them before the root file system has been - mounted. However,
the bootstrap loader is only able to load files that - are shared
FreeBSD binary objects. - The -f flag can be used to convert an arbitrary file
- firmfile
into shared object format (the actual conversion is - done using
the objcopy(1) and ld(1) commands). The resulting - files can then
be copied to the /boot/kernel directory, and can be - pre-loaded
directly from the boot loader prompt, or automati - cally by editing
the loader.conf(5) file. If desired, the files can - also be
loaded into memory at runtime using the kldload(8) - command.
- When an NDIS driver tries to open an external file,
- the
ndisapi(9) code will first search for a loaded ker - nel module that
matches the name specified in the open request, and - if that
fails, it will then try to open the file from the - /compat/ndis
directory as well. Note that during kernel boot - strap, the ability to open files from /compat/ndis is disabled: on
- ly the module
search will be performed. - When using the -f flag, ndiscvt will generate both a
- relocatable
object file (with a .o extension) and a shared ob - ject file (with
a .ko extension). The shared object is the one that - should be
placed in the /boot/kernel directory. The relocat - able object
file is useful if the user wishes to create a com - pletely static
kernel image: the object file can be linked into the - kernel
directly along with the driver itself. Some editing - of the kernel configuration files will be necessary in order
- to have the
extra object included in the build.
SEE ALSO
ld(1), objcopy(1), ndis(4), kldload(8), ndisapi(9)
HISTORY
The ndiscvt utility first appeared in FreeBSD 5.3.