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

FreeBSD Man 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)

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 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 indentifier
     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 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
	     (``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(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
	     filesystem	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 filesystem 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 /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 ker-
	     nel 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
     kldload(8), ld(1),	ndis(4), ndisapi(9), objcopy(1)

HISTORY
     The ndiscvt utility first appeared	in FreeBSD 5.3.

AUTHORS
     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>.

FreeBSD	10.1		       December	10, 2003		  FreeBSD 10.1

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=ndiscvt&sektion=8&manpath=FreeBSD+5.3-RELEASE>

home | help