[ofw] RFC on synchronization of .inf DriverVer and Build date, file ver & svn version number.

[Smith, Stan]

RFC on keeping driver .inf DriverVer file date & file version
definitions in sync with the build date and svn commit number.

Target drivers: ipoib, vnic & srp. HCA drivers in time.

The .inf directive 'DriverVer' can look like the following

DriverVer=06/11/2008,1.0.0000.1207

Where the 1st field is the date of the driver package version, with the
next 4 '.' separated fields comprising the driver.sys file version as
displayed when the mouse-point is held over the driver's .sys file.
The date field is used by Windows installers to decide if the to be
installed driver package is 'newer' than possibly existing installed
drivers.

By OpenIB convention the file version fields have been treated as such:

  1) IB release Major number - defined in trunk\inc\openib.def
  2) IB release Minor number - defined in trunk\inc\openib.def
  3) unused - defaulted to zero
  4) svn version number for sources used to build the .sys file -
%OPENIB_REV%.

Both DriverVer fields in the .inf file have been maintained by hand so
far.

I would like to propose a SW mechanism, such that the DriverVer fields
can
be updated in an automatic fashion yet allow for local override.

The WDK environment has introduced the stampinf.exe utility designed to
update the DriverVer directive date and file version fields.

By MS convention, from WDK examples, .inf files are renamed to .inx
files.
stampinf reads the .inx file and produces a .inf file as output.

The .inx file processing is handled during the processing of the SOURCES
file
and nmake/makefile processing.

Given the entire .inf file processing by stampinf is 'optional' and WDK
specific, the requirements are:

  In a driver source folder (e.g., trunk\ulp\ipoib\kernel\ )

  rename netipoib.inf to netipoib.inx
  add the new file makefile.inc to set makefile dependencies and invoke
stampinf.
  Add the following to the 'SOURCES file'

# WDK build only.
!if $(_NT_TOOLS_VERSION) != 0x700
INF_NAME=netipoib
NTTARGETFILES=..\..\..\bin\kernel\$(O)\$(INF_NAME).inf
MISCFILES=$(NTTARGETFILES)
!endif

NTTARGETFILES definition is magic in that if defined, then via
wdkxxx\bin\makefile.new, the file 'makefile.inc' is included in the
driver build.

Now when ipoib.sys is built, a processed netipoib.inf appears in
trunk\bin\kernel\obj*\arch\ with updated date and file version fields.


Handling the Major and Minor fields
-----------------------------------

makefile.inc invokes stampinf.exe in the following manner

$(STAMP) -f $@ -d * -v
$(IB_MAJORVERSION).$(IB_MINORVERSION).0.$(OPENIB_REV)

Since the makefile.inc file wants to use the same default Major and
Minor release numbers as defined in trunk\inc\openib.def there occurs a
problem in the tool chain.

At the build point which 'makefile.inc' processing occurs, openib.def
has not yet been included.
If one adds !include openib.def to makefile.inc, the build fails due to
a detected cyclic include of 'openib.def' error. Even if openib.def is
bracketed with
!ifndef _OPENIB_DEF_ ... !endif, the cyclic include error persists.

The solution was to define Major and Minor release numbers in the new
file trunk\inc\mod_ver.def.
'mod_ver.def' is included by both openib.def and makefile.inc;
one-stop-shopping.

A convenient side effect is that should a developer desire to override
Major and Minor release numbers, the presence of a local 'mod_ver.def'
(same folder as makefile.inc & SOURCES) will override the 'default'
definitions; just copy mod_ver.def to the local folder and modify.

Makefile.inc

# This file merely indirects to the common makefile fragment that is
# shared by driver components of the OpenIB Windows project.
#
# Assumption - ..\..\..\inc is in the current include search path.
# The current include file search path is used hence a local override is
possible.

!include inf_stamp.inc

inf_stamp.inc

# Transform .inx file to .inf file adding date + release major/min & svn
# stamps

_LNG=$(LANGUAGE)
_INX=.
STAMP=stampinf -a $(_BUILDARCH)

!INCLUDE mod_ver.def

..\..\..\bin\kernel\$(O)\$(INF_NAME).inf : $(_INX)\$(INF_NAME).inx 
    copy $(_INX)\$(@B).inx $@
    $(STAMP) -f $@ -d * -v
$(IB_MAJORVERSION).$(IB_MINORVERSION).0.$(OPENIB_REV)


Comments on the proposal?

IMHO - not an elegant solution, although passable.

One question which comes to mind, should the Major & Minor release
numbers be left solely to the discretion of the driver writer? This
would simplify things in that the mod_ver.def file would go away (back
to where we are today) w.r.t Maj/Min handling.


Thanks for reading this far,

stan.