ndiscvt
—
convert Windows® NDIS drivers for use with
FreeBSD
ndiscvt |
[ -O ]
[-i
inffile ]
-s
sysfile
[-n
devname ]
[-o
outfile ] |
The
ndiscvt
utility transforms a
Windows® NDIS driver into a data file which is used to build an
ndis(4)
compatibility driver module. Windows® drivers consist of two main
parts: a
.SYS file, which contains the
actual driver executable code, and an
.INF
file, which provides the Windows® installer with device identifier
information and a list of driver-specific registry keys. The
ndiscvt
utility can convert 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 kernel.
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.
The options are as follows:
-i
inffile
- Open and parse the specified .INF file
when performing conversion. The
ndiscvt
utility will parse this file and emit a device identification structure
and registry key configuration 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® 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/interface 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 resulting data. This can be
any file pathname. If outfile is a single
dash (‘
-
’), the data will
be written to the standard output. 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 contain a copy of the Windows®
.SYS driver image encoded as a
FreeBSD ELF object file (created with
objcopy(1)).
Turning the Windows® 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®, 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 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 automatically 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 kernel 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 bootstrap, the ability to open
files from /compat/ndis is disabled:
only 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 object file (with a
.ko extension). The shared object is
the one that should be placed in the
/boot/kernel directory. The relocatable
object file is useful if the user wishes to create a completely 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.
ld(1),
objcopy(1),
ndis(4),
kldload(8)
The
ndiscvt
utility first appeared in
FreeBSD 5.3.
The
ndiscvt
utility was written by
Bill Paul
<
wpaul@windriver.com>.
The
lex(1)
and
yacc(1)
INF file parser was written by
Matthew Dodd
<
mdodd@FreeBSD.org>.