bcfg(4dsp)


bcfg -- network driver configuration file format

Synopsis

   #$version 1
   #MANIFEST:
       FILES="all DSP files used by this driver
              continuation of list"
       [EXTRA_FILES="all non-DSP files used by this driver
              continuation of list"]
       [CONFIG_CMDS="cmd1
              cmd2"]
       [PRE_SCRIPT=preinstall_script_name]
       [POST_SCRIPT=postinstall_script_name]
   #DRIVER:
       TYPE=DLPI|MDI
       FAILOVER=true|false
       PROMISCUOUS=true|false
       DRIVER_NAME=name
       HELPFILE=name
       [WRITEFW=true|false]
       [UNIT=number_of_configured_cards]
       REBOOT=true|false
       RM_ON_FAILURE="value1 value2"
       NAME=value
       [CUSTOM_NUM=number_of_custom_specs]
       [CUSTOM[1]='values
                contents']
       [CUSTOM[2]='values
                contents']
       AUTOCONF=true|false
       [ISAVERIFY="param1 param2 ... paramn "]
       [DEPEND=value]
   #ADAPTER
       MAX_BD=highest_supported_adapter_number
       BOARD_IDS=values
       CONFORMANCE=hex_value
       [NET_BOOT=static|dynamic|autosearch]
       ACTUAL_RECEIVE_SPEED=speed
       ACTUAL_SEND_SPEED=values
       [DMA="values"]
       [INT="values"]
       BUS=bus
       [MEM="values"]
       NUM_PORTS=max_number_of_ports_on_board
       [PORT="values"]
       TOPOLOGY="ETHER | TOKEN | ISDN | ISDN | FDDI
            | ATM | X25 | FRAMERELAY | OTHER"

Description

Each network driver must have a bcfg file that provides information for the resource manager database. The bcfg file is a stanza(4dsp) file that is parsed by ndcfg(1M), a dual-parser lex(1) and yacc(1) program that enforces type and syntax checking. All configuration information that a user can modify must be defined in the bcfg file rather than the driver's Space.c(4dsp) and space.h files.

Use the ndcfg(1M) command to check the sanity of the bcfg file. It is also useful to check the /tmp/ncfgLog file that is created when a driver is installed with either the Network Configuration Manager or the -L option to the netcfg(1M) command.

The format of the bcfg file is:

A network driver can have multiple bcfg files, each with different NAME= and BOARD_IDS= fields. This may be implemented, for example, if a particular device model (identified by BOARD_IDS= enables a configurable feature (custom parameter) not found in other devices supported by the same driver. In this case, the driver must be able to handle all custom parameters found in all applicable bcfg files.

Multiple bcfg files are required if a driver supports multiple buses (for example, PCI and EISA); each bcfg file would have a different BUS= field entry.

Fields


#$version 1
Required first line for all bcfg files. Use #$version=0 for SCO UnixWare 2.0.x bcfg files, and #$version=1 for UnixWare 7 bcfg files. If this variable is not specified, it defaults to 0 to provide backward compatibility with earlier bcfg files that did not use this variable.

#MANIFEST:

FILES
A list of all files that are part of the driver's DSP and used by idinstall(1M).

EXTRA_FILES
Files that are not part of the driver's DSP but are required by the driver. These are listed here, with a full pathname, one file per line. This list should include all the executable files that are required to run the POST_SCRIPT= and PRE_SCRIPT= programs that are specified for this driver so that all over them will be bundled onto the netinstall floppy disks.

CONFIG_CMDS
List of commands that must be executed after the driver is loaded, such as commands that download code. Each line specifies the full path of the command with all options and arguments. The full path of the executable command file should also be listed in the EXTRA_FILES variable. netinstall executes each line after the files listed in EXTRA_FILES are downloaded.

PRE_SCRIPT
Name of optional script to be run before idinstall(1M). This can be used for back-end processing required when installing the device. Do not use this parameter to download firmware to the device; code the mdi_open_file(D3mdi) function in the driver code instead. The PRE_SCRIPT script runs once, the first time the driver is installed. Use an Rc script instead of this parameter for a script that needs to run every time the system is booted with this driver configured.

POST_SCRIPT
Name of optional script to be run after the idinstall delete operation. The POST_SCRIPT script runs only when the last instance of the card is removed from the system. Use an Sd script instead of this parameter for a script that needs to run every time the system is shut down with this driver configured.

#DRIVER:

AUTOCONF
Set to false for EISA, PCCARD, PCI, and MCA network drivers that are not automatically configured by the configuration manager when the kernel is initialized, such as network cards that are integrated into the mother board. This must always be false for PCCARD and PnPISA buses because the autoconfiguration mechanism does not automatically add information for these bus types to the resource manager. When this is false, the bcfg file must also define INT, PORT, MEM, and DMA that the network card supports, and the configuration process will proceed as if this was an ISA board, prompting the user for each of these addresses.

After the user supplies this information, netcfg(1M) changes the IRQ from 2 to 9 and adds the values of UNIT, IRQ, IOADDR, MEMADDR, and DMAC to the particular resource manager key.


DEPEND
Identifies other drivers on which this driver has a dependency. Normally, this value matches the value of the ``$depend'' field in the Master(4dsp) file. Drivers listed for this variable should not have their own bcfg files.

The value of the TYPE= variable determines which drivers are automatically installed by the interface, and so do not need to be listed as a value for the DEPEND= variable. The drivers automatically installed are:

TYPE=MDI idinstall dlpi, dlipbase, and netX
TYPE=DLPI none

 TYPE=MDI    idinstall dlpi, dlipbase,
             and netX
 TYPE=DLPI   none
Drivers specified through the DEPEND= variable are not available during network installation.

TYPE
Type of driver. Valid values are MDI and DLPI. DLPI is used for both SCO UnixWare 2.0 DLPI drivers and UnixWare 7 DLPI modules.

FAILOVER
Set to true to specify that a driver is failover-capable; otherwise set to false. To be failover-capable the driver must have a configurable MAC address and support the setting of the following multicast attributes:

  • single address

  • set all multicast addresses; see MACIOC_SETADDR(7mdi)

  • set of an ``unlimited'' number of single multicast addresses

Default value is false. If your driver implements the criteria listed in ``Failover (Network cards)'' in HDK Technical Reference, set FAILOVER=true so that netcfg(1M) can failover either from or to your card as required.


PROMISCUOUS
This mandatory parameter says how the driver responds to a MACIOC_PROMISC(7mdi) M_IOCTL(D7str) message. A value of true indicates that the driver implements promiscuous mode, while a value of false indicates that the driver does not support promiscuous mode. See ``Promiscuous mode'' in HDK Technical Reference.

DRIVER_NAME
Name of the driver associated with the network card defined by the bcfg file. If a network card requires more than one driver to be installed, use the DEPEND variable.

WRITEFW
Set to true for ISA cards that must program settings in firmware (on NVRAM/EEPROM). If true, operations will fail when the board cannot be found. If this is true, the ISA board must be present before it can be configured.

UNIT
Number of network adapter cards configured. Populate this variable for cards that must have the correct value for the ``UNIT'' field in the resource manager database and for network cards that work in both Single Port and Dual Port modes. When populated, this value will be saved in both the resource manager and the driver's file in the /etc/conf/sdevice.d directory. Note that UNIT does not provide a unique identifier for each board.

REBOOT
If true, installing this driver causes a shutdown and reboot.

Set to false for all loadable drivers.


RM_ON_FAILURE
Contains a list of files, beyond the normal DSP files, that should be deleted from the system if an error occurs while installing the driver. Typically, this includes all files listed in the PRE_SCRIPT or CONFIG_CMDS variable.

NAME
Full name of the network adapter, enclosed with double quotes. This is the text that is displayed to the user when selecting the number of cards installed. NAME may include spaces, but the text should be less than 25 characters and should not include commas, parentheses, or apostrophes.

Do not include version information here; version information is generated automatically from version information is generated automatically from the _ndversion variable in your source code. The definition must be in one of the following two forms:

   static char *_ndversion="28.2";
   static char _ndversion[]="28.2";
The _ndversion variable must be static or ndcfg(1M) will not allow users to configure your driver. The version itself (here 28.2) can be any printable string and must reflect any change is made to the driver, even if the change to your driver is in different file than the one containing the version string. This allows easy identification of the driver version to the user when installing an updated driver package or when running netcfg(1M) to configure the network adapter.

CUSTOM_NUM
Number of CUSTOM[x] variables that are specified. This determines the size of the CUSTOM[x] array. Valid values are 1 through 9, inclusive.

CUSTOM[x]
Define custom variables required by this card. x is an integer from 1-9 inclusive that uniquely identifies this custom variable for the driver. Each parameter gets a CUSTOM[x] variable, with 9 lines per parameter:

Line 1
Name of variable (maximum 11 characters) that is stored in the resource manager for this parameter. This parameter is always stored as a string, even if the value can be interpreted as a number or numeric range.

Line 2
Single or multivalued values that the driver can retrieve with the cm_getval(D3) function. Multiple values are separated by spaces. The selected value is stored in the resource manager as a string and not a number. This allows text options to be stored in the resource manager. The driver must convert this information from an ASCII string to a number if it requires a numeric value.

Line 3
List of choices (text strings) that are displayed to the user when the <F2> key is pressed.

To solicit free-form input from the user, populate this field with:

   __STRING__
The user input must be one word with no spaces, maximum 10 characters.

Line 4
Title displayed for choices in Line 3. Entire line is interpreted as a text string.

Line 5
Must be the text string ``RESERVED''.

Line 6
Text of the prompt that is displayed to the user, interpreted as a text string.

Line 7
Set to BASIC or ADVANCED to indicate the appropriate section in which the option should appear. Users are always prompted for BASIC options; ADVANCED choices are displayed only when the user selects the ``Advanced'' section in the netcfg(1M) command, so parameters that are specified as Advanced may not be written to the resource manager during driver installation. Driver writers should use an appropriate default value when ADVANCED parameters are not set.

Line 8
Applicable TOPOLOGY values for this parameter. The user will be prompted for this parameter only when one of the specified TOPOLOGYs is being used. This is useful for parameters that are used only for some media types and are not appropriate for other media, such as token ring routing parameters.

Line 9
Indicates the scope of this parameter. Valid values are:

BOARD
parameter is set only for this instance of the driver; changing the value of this parameter for one board should not change this parameter for other boards supported by this driver.

DRIVER
parameter is set for all instances of this driver. Used for parameters that are defined in this driver's Mtune(4dsp) and Dtune(4dsp) files. Using DRIVER scope causes an immediate build as discussed in ``Packaging and installing UnixWare 7 drivers'' in HDK Technical Reference.

GLOBAL
parameter is set for all MDI and DLPI drivers on the system. When idtune(1M) runs, it can affect any driver on the system. Consequently, GLOBAL scope forces a deferred build as discussed in ``Packaging and installing UnixWare 7 drivers'' in HDK Technical Reference. MDI drivers do not normally set this value.

PATCH
patch the kernel symbol found in Line 1 of /dev/kmem.

The CUSTOM[xx] variable is used by netinstall when the value is added to the resource manager database. If netcfg is run in silent mode, these values are not filled in, so the driver should define a reasonable default case and print a cmn_err(D3) CE_NOTE message if the parameter is not found in the resource manager database. This is especially true when Line 7 is set to ADVANCED and for mixed topology custom parameters.


ISAVERIFY
Declare the write-back capability of the firmware for ISA board drivers that use the CFG_VERIFY subfunction of the config(D2) entry point routine or, for DDI versions prior to 8, the _verify(D2) entry point routine. This does not include custom parameters. The following parameters are supported:
   WRITEIOADDR                    READIOADDR
   WRITEIRQ		       READIRQ
   WRITEMEMADDR		       READMEMADDR
   WRITEDMA		       READDMA
See ``ISA bus autoconfiguration'' in HDK Technical Reference.

#ADAPTER
These variables provide information about the actual hardware and are used only for hardware drivers.

MAX_BD
Highest numbered adapter supported by the driver. This is the number of adapters supported by the driver minus 1, because adapters are numbered up from 0. For example, if the driver supports up to 4 adapters on a single machine, set MAX_BD=3.

BOARD_IDS
List of all Board IDs supported by this network adapter card. This must match the related field in the Drvmap(4dsp) file. This includes what Smart Start might pass in as a Board ID. For example, for PCI cards, the Smart Start installation scripts append a PC prefix to the Board ID, such a PC102222000 for the AMD_PCnet card. Hex digits must be in uppercase.

EISA board IDs are in uncompressed form.

MCA board IDs are the form 0xDDDD where each D is a hexadecimal digit (0-9 or A-F). MCA board IDs must be four digits; use leading zeroes to pad if necessary. So 0x0ABC is correct; 0xABC is not.

PCI board IDs are in the form 0xVVVVDDDD where VVVV is the hexadecimal vendor ID and DDDD is the hexadecimal device ID. Note the lowercase ``x''.

PCI and MCA boards have a specific syntax. Wildcards cannot be used in bcfg files as they are in Drvmap files. Mixed-platform BOARD_IDS are not allowed; all IDs given must be correct for the single specified BUS= line and match the Drvmap file. Create multiple bcfg files, one for each BUS that the driver supports, with the appropriate BOARD_IDS for each BUS in the bcfg file.

Board revisions are not applicable for PCI devices.

If BUS= is PCI, EISA, or MCA, BOARD_IDS must be set unless AUTOCONF=false. In this case, you must also supply ISA parameters or set BUS=ISA and emulate an ISA board.


CONFORMANCE
Version of the applicable driver interface specification to which this driver conforms, expressed as a single hexadecimal number with a leading 0x. Valid values are:

Interface Value Notes
MDI 2.0 0x0200 see MDI_VERSION in mdi.h header file
DLPI 0x02 see DL_CURRENT_VERSION in dlpi.h header file

 Interface   Value    Notes
 MDI 2.0     0x0200   see MDI_VERSION in
                      mdi.h header file
 DLPI        0x02     see
                      DL_CURRENT_VERSION
                      in dlpi.h header
                      file


ACTUAL_RECEIVE_SPEED
Relative speed of this card/driver combination. It must be set to a single, positive decimal integer number. Valid values can be obtained from the output of the spm(1Mcert) utility. The value 0 is set by ndcfg(1M) for SCO UnixWare 2.0.1 bcfg files to indicate that this value is unknown.

The MAC_INFO_ACK(D7mdi) primitive captures this information and passes it to the DL_GET_STATISTICS_REQ(D7dlpi) primitive. This variable provides some measure of performance of a particular card/driver combination to protocol stacks that choose to access it.


ACTUAL_SEND_SPEED
Relative speed of this card/driver combination. It must be set to a single, positive decimal integer number. Valid values can be obtained from the output of the spm(1Mcert) utility. The value 0 is set by ndcfg(1M) for SCO UnixWare 2.0.1 bcfg files to indicate that this value is unknown.

This variable provides some measure of performance of a particular card/driver combination to protocol stacks that choose to access it. It does not reflect the speed of the underlying media that is available to stacks as part of a returned DL_GET_STATISTICS_ACK(D7dlpi) primitive. The MAC_INFO_ACK(D7mdi) primitive captures this information and passes it to the DL_GET_STATISTICS_REQ(D7dlpi) primitive.


DMA
List of DMA channels supported by this network card. The numbers are in decimal.

INT
Interrupt vectors supported by the network card. Use decimal numbers, separated by a space, and surrounded by double quotes (``"''), for example:
   INT="2 3 4 5 6 9"
Drivers that use IRQ 2 should include both 2 and 9 in this parameter list for user convenience, even though ndcfg(1M) silently converts IRQ 2 to IRQ 9 so that only IRQ 9 will really be read.

This variable is not used for autoconfigured drivers.


BUS
Bus type of the network card. Valid values are ISA, EISA, PCI, MCA, and PCCARD (not PCMCIA). PnPISA support is not yet fully implemented, so this cannot be specified for BUS= at this time. This value cannot be multivalued. If multiple bus types are supported, create a separate bcfg file for each applicable bus.

If BUS= is set to PCCARD, AUTOCONF=false must also be set. Certain EISA boards have this requirement.

This variable limits the selections that the user sees. Users will only be able to select the bcfg file(s) for bus types that are configured on the machine.


MEM
Memory addresses that the network card supports. This is a list of address ranges expressed as:
   MEM="start1-end2 start2-end2"
Memory addresses are displayed in uppercase hexadecimal notation, without a leading 0x. For example:
   MEM="D0000-D1FFF D2000-D3FFF"
This variable is not required for autoconfigurable drivers.

NUM_PORTS
Number of ports supported on a single card, used for network cards that support more than one port simultaneously. This variable is not currently implemented; use the CUSTOM variable to set this.

PORT
I/O addresses supported by this network card. This is a list of address ranges expressed as:
   PORT="start1-end2 start2-end2"
I/O addresses are displayed in uppercase hexadecimal notation, without a leading 0x. For example:
   PORT="3FA-3FF 3BC-3EF"
This variable is not required for autoconfigurable drivers.

TOPOLOGY
Topologies supported by the hardware and driver. It can be multivalued if the card is dual-topology capable. netcfg(1M) uses this variable to select drivers of a particular type.

For dual-topology cards, you must also define a CUSTOM[x] variable to query the user for more information about which topology the card should use if it cannot autodetect the media in use. If each TOPOLOGY must uniquely match a BOARD_IDS value, you can set up separate bcfg files for each TOPOLOGY. The topology is required so that the MAC_INFO_ACK(D7mdi) primitive can contain the correct single value (MAC_CSMACD, MAC_TPR, or MAC_FDDI).

Semantic checks performed

The following syntax and semantic checks are performed on the bcfg file each time it is loaded:

  1. Verify that all mandatory variables for the applicable ``#$version'' are defined.

  2. Verify that all variables that take values of true or false are defined to one of these.

  3. Verify that all variables that contain numbers or numeric ranges have numeric values in the correct base. For example, interrupts are expressed in decimal values and memory address ranges are expressed in hexadecimal values.

  4. Verify that variables that can contain only a single value do not define multiple values.

  5. Verify that the INT and MEM variables are defined if BUS=ISA.

  6. Verify that no unknown variable names are defined.

Differences between versions

#$version 1 identifies bcfg files for UnixWare. This replaces the AOF, acfg, SYSDB, and lkcfg file formats that were supported in earlier product releases. SCO UnixWare 2.0 bcfg files do not include the #$version definition and are assumed to be version 0. The differences between version 1 and version 2 bcfg files are:

Note that the FAILOVER parameter has no effect on UnixWare 70.0 systems, although it must be set to a valid value. For UnixWare 7.0.1 and subsequent releases, netcfg(1M) checks if FAILOVER=true and, if so, takes appropriate action.

Files


/etc/inst/nd/mdi/*/*.bcfg

/etc/inst/nics/drivers/*/*.bcfg

References

ndcfg(1M), netcfg(1M), Space.c(4dsp)

spm(1Mcert) in the HDK documentation.

``Configuring UnixWare 7 MDI drivers'' in Developing MDI network adapter drivers

``DSP (Driver Software Package)'' in HDK Technical Reference


25 April 2004
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004