INF files are typically provided with the hardware and driver on diskette or CD. The structure and content of the INF file is the responsibility of the driver author. INF File StructureAn INF file is a simple text file divided into sections, with each section designated by an identifier within closed braces ([]). Some section names are required, while others are driver-specific. Entries beneath each section control some installation action, or they link or enumerate other sections. The order that sections appear in a file is unimportant, since each section is named and linked. A section continues until either another section or the end-of-file is encountered. The unique name that specifies a section is case-insensitive and should be limited to 28 characters in length to maintain compatibility with Windows 98. Section names can include spaces, but only if the entire name is quoted. The underscore and dot characters are allowed. The general format of section entries is entry = value [, value...] where entry is a directive, keyword, or filename, and value is the attribute that is to be applied to entry. An illustration of the linkage of section names is shown in Figure 16.1. Figure 16.1. INF file section linkage.The entry or value names can be specified as a string token, which is a substitution string enclosed within percent signs (%). A separate INF section, [Strings], provides the string token values for a given language ID. Version SectionA valid INF file begins with a section named [Version], which acts as a header and signature for the entire INF file. The allowed and required entries within the [Version] section are listed in Table 16.1. Manufacturers SectionAnother required section is the [Manufacturers] entries. Each entry within this section lists the devices and their drivers that are installed by the INF file. The form of each entry is manufacturer=model where the manufacturer lists an INF-unique name for the producer of one or more models of hardware being installed. The model value points to another INF section name that lists the further direction for driver installation of the hardware model. Models SectionFor each model listed within the [Manufacturers] section, a corresponding section must appear as specified by model. The form of each model entry is device-description=install-section-name,hw-id[,compatible-id...] where device-description represents a human-readable listing of the device model and a short description. This string is presented to the user in a dialog box during some installations, so it may need to be provided in multiple languages as a string token.
The value of install-section-name, also referred to as the [DDInstall] section, represents yet another INF section that directs further installation. The hw-id value is the PnP identifier returned by the hardware device during its announcement on a PnP-compatible bus. For example, USB\VID_045E&PID_00B identifies the Microsoft HID (Human Input Device) keyboard device on a USB. Any number of compatible-id values can be appended signifying that the same install script is to be used for any device contained in the list. DDInstall SectionNear (but not quite at) the bottom of this linked list of INF section names is the [DDInstall] section, whose name is actually specified uniquely for each model of each manufacturer from the [Models] sections. The allowed and required entries within the [DDInstall] section are listed in Table 16.2. While only the AddReg entry is syntactically required, the CopyFiles entry is an essential directive for [DDInstall] sections. It takes the form CopyFiles=file-list-section[,file-list-section...] or CopyFiles=@filename The former version is more common in that it allows an indirect pointer to another section that contains a list of files to be installed. However, for simple driver installations, the direct filename approach gets the job done. Both the AddReg and CopyFiles directives are explained in further detail in the next two sections.
CopyFiles SectionThe [CopyFiles] sections of an INF file are uniquely named and referenced from CopyFiles directives in the [DDInstall] sections. Each entry within the section takes the form destination-filename[,source-filename,temp-filename,flag] where destination-filename is the ultimate target name for the file to be copied. If the source filename is not the same, source-filename must be specified. The temp-filename value is an anachronism (though still required for Windows 98) that specifies an intermediate filename for the new file until the next system reboot. For Windows 2000, the value is ignored. The flag value specifies the disposition of the new target file and is described in Table 16.3. The bits within the flag value are ORed to effect multiple actions. Several actions are mutually exclusive (e.g., WARN_IF_SKIP and NOSKIP) and the documentation should be checked when in doubt.
Since the syntax for the [CopyFiles] entry does not include an option to specify a disk or path for the source file, other INF sections, [SourceDisksNames] and SourceDisksFiles] must be used. The files copied by the entries within the [CopyFiles] section are targeted by yet another INF section, [DestinationDirs]. AddReg SectionThe [AddReg] sections of an INF file are uniquely named and referenced from AddReg directives in the [DDInstall] sections. The purpose of the section is to provide directives that add or modify entries in the target system registry. Each entry within the section takes the form reg-root[,subkey,value-name,flags,value] where reg-root is an abbreviation for one of the Registry hives, as listed in Table 16.4. The value designates the hive being modified. The subkey value represents the key name beneath the hive, with subkeys separated in the hierarchy by the backslash (\) character. For example, Software\W2KDriverBook\ Driver\Setting is a valid subkey in either the HKCU or HKLM hive.
The value-name designates the Registry value being added or modified. Each system Registry key contains zero or more values that hold different types of data. The Registry Editors list values of a subkey in the right-hand pane. Both the value name and the value data appear in this pane. The left pane lists only subkeys. Figure 16.2 illustrates the relationship between Registry terms. Figure 16.2. System Registry terminology.The flags specify the type of data that is to be stored and the possible bit values for flags is listed in Table 16.5.
The significance of system Registry entries to a driver installation is discussed in a later section of this chapter. SourceDisksNames SectionIf the distribution of the driver files controlled by the INF file spans more than a single disk (diskette or CD), the INF file must include a [Source-DisksNames] section. This section includes one entry for each disk within the distribution set. The entry takes the form diskid=disk-description[,tagfile,unused,path] where diskid is a unique number within the distribution set. Typically, disks are numbered starting at 1. The disk-description tag is a human-readable text string that can be used to prompt the user for the proper disk as needed. The tagfile value assumes a dual role. To ensure that the user supplies the correct disk during the installation process, the tagfile value is verified as existing on the inserted media before the install process continues. If the tagfile file is missing, the user is reprompted to insert the correct disk. If the tagfile value contains a .CAB extension, the file is further assumed to be a collection of compressed files for the source of driver files on the disk. The path value is a root-relative disk path value for the source of driver files on the disk. Like the tagfile value, path is optional. If omitted, the root directory is assumed to be the source of the files. SourceDisksFiles SectionA driver INF file must also contain a section named [SourceDisksFiles]. This section lists the filenames used during installation of the driver. Each file corresponds to one entry within the section and takes the form filename=diskid[,subdir,size] Naturally, the diskid value specifies a disk within the [SourceDisksNames] section where the filename is to be found. The optional subdir value specifies a path on the disk for the file. The optional size value specifies the uncompressed size of the file in bytes. An installation process can use the size to determine if the source file fits on the target system prior to attempting the copy. DestinationDirs SectionThis required section in an INF file specifies the target directory for source files. Without knowledge of this section, an installation program or process would have no target directory in which to copy files. The entries in the [DestinationDirs] section take the form file-list-section=dirid[,subdir] or DefaultDestDir=dirid[,subdir] where file-list-section specifies a section called out in a [CopyFiles] directive. It specifies that all the files copied by a directive install into the specified directory. For the entry DefaultDestDir, the specification applies to all [CopyFiles] directives that do not otherwise associate with a file-list-section within the DestinationDirs section. The dirid value specifies an enumerated value for a destination directory according to Table 16.6. If the value subdir is supplied, it specifies a relative path beneath the directory called out by dirid. DDInstall.Services SectionIn order to actually have the copied file(s) act as a driver on the target system, the Service Control Manager (SCM) must be notified. As discussed in chapter 6, entries are made in the Registry under HKLM\System\CurrentControlSet\Services for each driver installed under Windows 2000. A ServiceType value of 1 signifies a kernel-mode device driver. StartType designates at what point in the boot process the driver loads (3 denotes on-demand or manual start). The ErrorControl value determines what happens during the driver load if an error is encountered. ServiceBinary value points to the location of the driver file (.SYS file), but may be omitted if the binary is located in the %windir%\system32\drivers directory and has the same name as the subkey name underneath HKLM\...\Services.
The entries of the DDInstall.Services section include an entry of the form AddService=ServiceName,[flags],service-install- section[,eventlog-install-section] where ServiceName represents the name of the service, typically the name of the driver, sans the .SYS extension. The flags value is described in Table 16.7.
The service-install-section and optional eventlog-install-section values call out additional INF section names that control service value entries (such as ServiceType and StartType). ServiceInstall SectionThe [ServiceInstall] section, whose name is actually specified uniquely for each AddService entry within the DDInstall.Services sections, controls the installation of a driver into the Service Control Manager. The allowed entries within the [ServiceInstall] section are listed in Table 16.8.
INF ExampleIf the preceding explanation of INF files appears overly complex, a simple example may clarify. In the following example, a two-file driver is controlled by the INF file. The driver binary, Launcher.SYS, is copied into the system's driver directory (e.g., WINNT\System32\Drivers). A separate help file, Launcher.HLP, is copied into the help directory of the system (e.g., WINNT\Help). [Version] Signature="$Windows NT$" Class=Missiles ClassGUID={C9B3D080-6889-11d4-93FC-444553540000} Provider=W2KDriverBook DriverVer=07/04/2000,1.00.2468.1 ; Comments follow a semicolon [DestinationDirs] ; Specify where files are copied to DefaultDestDir=12 ; %windir%\system32\drivers CopyLaunchHelp=18 ; standard help directory [Manufacturer] W2KDriverBook=MyMfgName ; call out a model section [MyMfgName] ; begin a Models section ; Our list of devices follows: "ISA Missile Launcher"=InstallLauncher,ISA\Launcher [InstallLauncher] ; begin a DDInstall section CopyFiles=CopyLaunchFiles ; call out a CopyFiles sec. CopyFiles=CopyLaunchHelp ; and one for the help files AddReg=LaunchRegSection ; call out an AddReg section [CopyLaunchFiles] ; begin a CopyFiles section Launcher.sys [CopyLaunchHelp] ; a second CopyFiles for Help file Launcher.hlp [LaunchRegSection] ; begin an AddReg section ; Provide a DWORD registry value of 0 for our device: HKR,"Parameters","Coordinates" ,FLG_ADDREG_TYPE_DWORD,0 [SourceDisksNames] ; This section is not really required because we have ; only two files and they probably fit on one disk. 1="Missile Launcher Driver Files" [SourceDisksFiles] ; Similarly, since everything came from one disk, ; we don't really need this section either. Launcher.sys=1 Launcher.hlp=1 [InstallLauncher.Services] ; DDInstall.Services sec. AddService=Launcher,2,LaunchService ; Setup the SCM registry entries so driver can start [LaunchService] ServiceType=1 ; driver StartType=3 ; on-demand (manual) ErrorControl=1 ; report errors ServiceBinary=%12%\Launcher.sys ; path to driver Validating INF SyntaxThe DDK includes a rudimentary tool, CHKINF, in the Tools directory of the DDK. It relies upon the Perl scripting engine, available for download from http://www.perl.com. While the tool is not without merit, it reports numerous errors when checking standard Microsoft INF files. The output from the tool is in the form of an HTML file. The DDK Tools directory also contains a utility to simplify the construction of an INF file, GENINF.EXE. The tool must also be classified as rudimentary but may assist first-time authors. Finally, a simple tool supplied with the DDK, STAMPINF.EXE, provides a quick mechanism to add or modify the version information in an INF file.
|