IBABUILD
Intel(R) Boot ROM Creation Utility for DOS systems
====================================================================

DISCLAIMER:
-----------

Copyright (c) 2003-2006, Intel Corporation. All rights reserved.
Intel Corporation, 5200 NE Elam Young Parkway, Hillsboro, OR 97124-6497.
Intel Corporation assumes no responsibility for errors or omissions in
this document or software. Nor does Intel make any commitment to update
the information or software contained herein. Software product is
supplied "as is" and may not be fully functional.

Other product and corporate names may be trademarks of other companies
and are used only for explanation and to the owners' benefit, without
intent to infringe.

INTRODUCTION:
-------------

IBABuild is a flash programming and image distribution tool.  It is designed 
for engineering, test, and OEM use only.

IBABuild is not an end-user program.

IBABuild can create Intel Boot Agent ROM images with various combinations of
the following components:
- Base Code (BC) - contains the PXE API and support code.  This also includes
  the IP stack that uses the UNDI driver for booting. 
- Setup Menu - the Ctrl-S screen, plus routines to read the adapter EEPROM and
  determine configuration.
- UNDI driver - the network driver for the card (refers to 16-bit UNDI only).

Split ROM implementation is supported, as are LOM images.

IBABuild is generally used to create ROM image files, which can be integrated
into a BIOS, or programmed into an adapter's flash.  As a convenience,
IBABuild can also program an image directly to flash at runtime.

IBABuild can also generate Intel HEX format image files for use with flash
programming tools.

IBABuild is a DOS executable that can run under Microsoft Windows.  However,
the flash programming feature will not work under Windows.  The system must
be booted to a MS-DOS prompt in order to program flash.  All other operations
are supported under Windows.

IBABuild is not an end-user program!  It does not duplicate any of the 
configuration parameters that IBAUtil supports and thus cannot be used
to control and configure Intel Boot Agent.  It is simply designed to 
create ROM images.



RUNNING IBABUILD:
-----------------

    IBABuild [-option, -option]...



If IBABuild is run under DOS without any command line options, it displays a 
listing of all of the Intel Network adapters found in the system.

If IBABuild is run under Windows without any command line options, it displays
a copyright and version message, but performs no other options.

GENERAL OPTIONS

   -HELP or -?
        Displays command line help and exits.  When -HELP is used, all other 
        parameters are ignored.

   -EXITCODES
        Displays exit code help.  When -EXITCODES is used, all other parameters
        are ignored.

   -IMAGEVERSION or -IV
        Displays the image versions stored within the utility. When 
        -IMAGEVERSION is used, all other parameters are ignored.

NOTE: The precedence of these parameters is as listed above.  If two or more
of the above parameters are specified, the first one in the list is used and
the others are ignored.


OUTPUT SELECTION OPTIONS

   -ALL
        Selects all adapters found in system for use with flash programming.

   -NIC=XX
        Selects a specific adapter for use with flash programming.  XX is the 
        adapter number, from 1 to 40.

        NOTE: Flash programming is not supported under Windows.

   -OF=[NIC|LOM|FLB|HEX]
        Selects the output format of the image.  If this parameter is present, 
        then the image is written to a disk file in the current directory. The 
        name of the disk file is determined by IBABuild using the file naming 
        conventions described below.

NOTE:  Only one of the above three parameters is allowed at any time.  
Use of two or more of these parameters in any combination is a fatal error.

IMAGE CREATION OPTIONS

   -DEVID=XXXX,XXXX,XXXX,XXXX
        Specifies which device IDs are to be included in the output image. This
        parameter is required if IBABuild is writing to an output file.  If the
        file type is .NIC, .LOM, or .HEX, one and only one device ID must be 
        specified. If the file type is .FLB, one to 16 device IDs may be 
        specified.

   -IMAGE={BC,UNDI,SETUP}
        Specifies which pieces of Intel Boot Agent should be included in the 
        image. One or more of the listed options must be included.  Some 
        combinations are illegal or nonsensical and will generate errors.

FLASH PROGRAMMING OPTIONS

   -UPDATE=[filename]
        Updates the flash on the specified NIC with the specified file.  No 
        image is built and no processing of the input file is performed, unless
        the input file is an FLB file.  In this case, the file will be 
        validated for use with the specified adapter and the device ID of the 
        adapter will be inserted into the image as it is programmed.  This 
        parameter must be used with -NIC or -ALL. This parameter may not be 
        used with any of the image creation options or with the -OF option.

        NOTE: the -UPDATE parameter is not supported under Windows.


IBABUILD EXAMPLES:
------------------
IBABuild is generally used in three different scenarios:

   - To create an image file or files to be programmed into flash, either as
     part of the NIC manufacturing process, or as part of the BIOS programming
     process for LOMs.
   - To create and program an image directly into a NIC.
   - To program an arbitrary image file into a NIC.

While it is possible (and perhaps even probable) that IBABuild will be used
in other ways, these three scenarios capture the vast majority of IBABuild
uses.

A few examples of each scenario are given in this section.  These examples
are not intended to be comprehensive and will not cover every possible
combination of IBABuild parameters.  They are simply intended to illustrate
how the various parameters are used.

To create an image file containing SETUP, UNDI, and BC for use in a NIC based
on the 82540EM Ethernet controller:

	IBABUILD -OF=NIC -IMAGE=SETUP,UNDI,BC -DEVID=100E

The output of this command is the file name BA????L2.NIC, where ???? is the
Intel Boot Agent version number for Gigabit adapters.

To create a minimum-size split ROM implementation for a LOM implementation of
the 82551QM Fast Ethernet controller:

	IBABUILD -OF=LOM -IMAGE=BC
	IBABUILD -OF=LOM -IMAGE=UNDI -DEVID=1229

These commands will create two files:  BA????BC.LOM and Ba????X2.LOM,
where ???? is the Intel Boot Agent version number for Fast Ethernet adapters.

To program an UNDI/SETUP/BC image into all NICs in the system:

	IBABUILD -ALL -IMAGE=UNDI,BC,SETUP

To program the file FOO.FLB into a NIC:

	IBABUILD -NIC=1 -UPDATE=FOO.FLB

APPLICATION NOTE:
-----------------

The FLB file format allows up to 16 supported device IDs to be included in 
the FLB file header structure. In order to support more than 16 device IDs, 
Windows PROSet allows FLB images to be concatenated together.  This is 
accomplished by using IBABuild to generate two FLB images with support for 
up to 16 devices each, and then concatenating the FLBs together using the 
"copy" command as follows:

        ibabuild -of=FLB -image=bc,undi,setup -devid=1008,1009,100C,100E
        ren ba*l2.flb bal2-1.flb
        ibabuild -of=FLB -image=bc,undi,setup -devid=107C,108A
        ren ba*l2.flb bal2-2.flb
        copy /b bal2-1.flb+bal2-2.flb ba1226l2.flb

LEGAL FLASH IMAGE COMBINATIONS
------------------------------

The following rules are used to determine if a flash image is valid:

- SETUP may not be in an image alone.

- BC may be put in a LOM image alone.  (This is a split image.)

- UNDI may be put in a LOM image without BC.  (This is the other half of a 
  split image.)

- Unless it is completely alone in a .LOM (split) image, BC must always be 
  accompanied by UNDI.

- If the image is .NIC, .FLB, or .HEX, and UNDI is present, BC must be present.


IMAGE FILE NAMING CONVENTIONS:
------------------------------

In order to be able to easily identify various versions of the boot agent for
different adapters, the flash image file name contains information about its
contents. The file name has the following format:

	BAxyzztn.eee

where:  x   is the major version number of the agent in decimal
        y   is the minor version number of the agent in decimal
       zz   is the build number of the agent in decimal
        t   is the type of image
        n   is the adapter family the image supports
      eee   is the type of image file
	 
Image types:	
        L  - Monolithic PXE (UNDI+BC) with setup menu
        Q  - Monolithic PXE (UNDI+BC) without setup menu
        T  - Split PXE UNDI driver with setup menu. LOM only.
        X  - Split PXE UNDI driver without setup menu. LOM only.
        BC - Split PXE Base Code image.  No family is specified.  LOM only.

Adapter families:
        1 - Fast Ethernet
        2 - Gigabit
        4 - 10 Gigabit

Image type extensions:
        FLB - Flash Library file supporting multiple NICs
        NIC - Image file for use with a NIC
        LOM - Image file for use with a LOM
        HEX - Image file (NIC format) for use with flash programming tools

For example, build 18 of version 1.2 of the monolithic PRO/1000 adapter boot
agent would be named BA1218L2.FLB.

---End of IBABUILD.TXT---