Sample Update Tool Readme file.
Licensed Documentation described in "license.pdf".
INTEL CONFIDENTIAL
_____________________________________________________


1) Building the application

The application can be built with Microsoft Visual Studio 2005.
The file "SampleUpdateTool\wmi\SampleUpdateTool.sln" contains solution file for the IDE compiler.

You can also compile it automatically from command line by launching 
"SampleUpdateTool\BuildMsvc2005.bat" file - it will open IDE, compile the project and close the IDE.
The resulting executable file will be "SampleUpdateTool\wmi\Debug\SampleUpdateTool.exe".


2) System requirements

The application will run only on Windows Server 2003 R2/2008 R2 operating systems with Windows Remote Management installed.

Please note: 
 - Windows Remote Management is not installed by default, but is available as 
   the Hardware Management feature through the Add/Remove System Components feature 
   in the Control Panel under Management and Monitoring Tools.
 - At the time of creating the application the BIOS did not have proper support for the BMC 
   ( there were no proper ASL  entries in BIOS ) and standard Windows driver could not recognize the BMC. 
   All the tests  were made with Intel IPMI driver installed instead of standard Windows Hardware Management.
   The driver can be downloaded from Intel Web page:
        IMB/IPMI Driver for Microsoft Windows* [IMBDriver10-Build10.exe] 
        http://downloadcenter.intel.com/Detail_Desc.aspx?strState=LIVE&ProductID=37&DwnldID=12299&agr=N&lang=eng&PrdMap=37
   The driver, because to its features, requires some extra code not needed when using 
   standard Windows driver ( for such case please use Debug_use_MS_driver solution configuration or command line switch ).
   Such scenario has been tested on Windows Server 2008 R2.
 - Admin should ensure enough OS resources to be allocated for the application to run correctly. Especially processor time,
   adjusted by priorities of processes - failure to do so may significantly increase update time or even cause it to fail
   due to communication timeouts.

3) Running the application

The application should be executed in following way:

SampleUpdateTool.exe 0x88 SpsOperational.bin

The arguments:
- "0x88" - the  ME address (default value )
- "SpsOperational.bin" - the ME code partition to be downloaded


There are also other optional arguments:
- #3 - IpmiWindowSize (0 default) - IPMI window message size
- #4 - BridgeChannelId (6 default) - BMC bridge channel ID
- #5 - ImgBytesInFrame (55 default for Intel driver, 68 for MS driver) - number of image bytes in one IPMI frame

The value of IpmiWindowSize specifies how many IPMI requests will be sent without waiting for their response.
In particular:
- Value "0" - means that no IPMI requests will be sent in advance before getting response for 
              current request;
- Value "2" - means that the stack will send up to 3 requests without waiting for the response. 
              Getting the response will generate next request - the stack will try to keep up 
              to 3 unanswered request in communication queue.

Due to ME buffer limitations, values 0..15 should be used.
Higher value gives faster transmission (keeps ME always occupied, no time is wasted on transmission delays).

The default value is 0 - the slowest but the safe one. The optimum value is system specific.


4) Tuning the application.

The Sample Update Tool has been tested in three scenarios (1MB image):
 - update with ME connected directly to PC SMBus host adapter (http://www.totalphase.com/products/aardvark/i2cspi/)
 - update through BMC communicating with the application by WMI mechanism using Intel IPMI driver
 - update through BMC communicating with the application by WMI mechanism using Microsoft IPMI driver

The first case (which is engineering case only - no source code distributed) gave following results:
-  direct update with window size 15 - 70 seconds
-  direct update with window size  0 - 75 seconds

The second case:
-  update through WMI and Intel IPMI driver (uses KCS to communicate with BMC) window size 5 - about 330 seconds

The third case:
-  update through WMI and Microsoft IPMI driver (uses KCS to communicate with BMC) window size 5 - about 680 seconds

So big difference is caused by synchronous communication between WMI and BMC.

 
5)  Notes.
The sample code does not provide SHA algorithm implementation. Verification process of image file before 
burn operation requires own implementation of SHA-256 algorithm. Such implementation should be placed in 
the CheckModuleHash function body.


6)  Short description of files included in the Sample Update Tool.
  + SampleUpdateTool\sha\sha_call.cpp
      The file contains empty function for own implementation of SHA-256 algorithm for additional
	  functionality of Sample Update Tool.
  + SampleUpdateTool\wmi\hal_wmi.cpp 
      The file contains WMI transport layer for IPMI messages. Implements simple send frame /receive frame type functionality.
  + SampleUpdateTool\wmi\hal_intel.cpp
  + SampleUpdateTool\wmi\hal_intel.h
      The files contain special functionality required for Intel IPMI driver. The Intel driver 
      implements polling of message queue.
      The functionality cause that responses to bridged messages (sent with SendMessage IPMI 
      command) are intercepted by the driver. 
      The functions implement retrieval of messages queued in the driver.
  + SampleUpdateTool\wmi\SampleUpdateTool.sln
  + SampleUpdateTool\wmi\SampleUpdateTool.vcproj
      Microsoft Visual Studio solution/project files.
  + SampleUpdateTool\spsloader.cpp
      Application layer of tool. Implements high level IPMI message sending (according to update
      algorithm).
  + SampleUpdateTool\spsloader.h
      Common header file. Contains all definitions for the application.
  + SampleUpdateTool\crc8.cpp
      Helper function implementing standard crc8 algorithm.
  + SampleUpdateTool\ipmi.cpp
      Ipmi stack. Generic, but not complete (just for the update).
  + SampleUpdateTool\stdafx.cpp
  + SampleUpdateTool\stdafx.h 
      Standard Microsoft Visual files used when precompiled headers are enabled.
  + SampleUpdateTool\readme.txt
      This file.
  + SampleUpdateTool\BuildMsvc2005.bat
      Batch file which executes compilation of the project from command line. Launches the IDE, 
      compiles and closes IDE automatically.
  + SampleUpdateTool\license-notices.txt
      License notices.
  + SampleUpdateTool\license.pdf
      The license of the Sample Update Tool.
