Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
NDISCVT(8)		FreeBSD	System Manager's Manual		    NDISCVT(8)

     ndiscvt --	convert	Windows(R) NDIS	drivers	for use	with FreeBSD

     ndiscvt [-O] [-i inffile] -s sysfile [-n devname] [-o outfile]
     ndiscvt [-f firmfile]

     The ndiscvt utility transforms a Windows(R) NDIS driver into a data file
     which is used to build an ndis(4) compatibility driver module.
     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 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 identi-
     fication 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 conver-
	     sion.  The	ndiscvt	utility	will parse this	file and emit a	device
	     identification structure and registry key configuration struc-
	     tures 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	con-
	     vert 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

     -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	file.  The latter file will contain a copy of
	     the Windows(R) .SYS driver	image encoded as a FreeBSD ELF object
	     file (created with	objcopy(1)).  Turning the Windows(R) driver
	     image directly into an object code	file saves disk	space and com-
	     pilation 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	direc-
	     tories 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 ker-
	     nel 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 disk-
	     less/PXE booting),	the files need to be pre-loaded	by the boot-
	     strap 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	abil-
	     ity 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 ker-
	     nel configuration files will be necessary in order	to have	the
	     extra object included in the build.

     ld(1), objcopy(1),	ndis(4), kldload(8), ndisapi(9)

     The ndiscvt utility first appeared	in FreeBSD 5.3.

     The ndiscvt utility was written by	Bill Paul <>.  The
     lex(1) and	yacc(1)	INF file parser	was written by Matthew Dodd

FreeBSD	6.0		       December	10, 2003		   FreeBSD 6.0


Want to link to this manual page? Use this URL:

home | help