============================ Description ============================ WD_download 1.4.3 using: Turquoise Library 1.11.0.1 Updates firmware (microcode) on Western Digital (WD) drives. WD_download is a console application that downloads a firmware file to WD drives that are connected to your local system. WD_download supports multiple command line switches (-dev and -model) that allow you to select which drives will have firmware downloaded. If you do not specify "-dev" or "-model", you will be prompted to select which drives will have firmware downloaded. You can select all, none, or a subset of the drives. The firmware file that you specify must be the correct type for the drives; otherwise, the firmware download operation will fail. By default, WD_download discovers all WD drives (including those with mounted volumes). However, WD_download's configuration file (WD_download.ini) can be modified to discover only partitioned drives (it will exclude drives with mounted volumes). To do this, you must "comment out" the DriveFilter setting in WD_download.ini as follows (refer to the comments in WD_download.ini for additional details). Change these lines: [tqpl-os-devices] ScanTimeout=-1 DriveFilter=AllowAll To this: [tqpl-os-devices] ScanTimeout=-1 # DriveFilter=AllowAll When you specify a single firmware file name in the WD_download command line (via the "fwFilename" argument), you can update the firmware on only one drive model at a time. To download firmware to multiple drive models, use the "-model mFile" switch. Refer to "The -model Switch" section for details. WD_download performs the following steps: 1) Lists the number of WD drives that are attached to the local system and displays details for each drive: device number, model string, serial number, and firmware revision. 2) Prompts you to download firmware to one or more of the listed drives; respond as described below. This step may be bypassed by specifying "-batch_mode", "-dev devlist", or "-model mFile" in the command line. When "-batch_mode" is specified, firmware will be downloaded to all discovered WD drives that are connected to your local system. When "-dev devlist" is specified, firmware will be downloaded to only those drives that are selected in "devlist". When "-model mFile" is specified, firmware will be downloaded only to the drive models listed in "mFile". 'N', 'n' or = DO NOT download firmware. 'ALL' or 'all' = Download firmware to all drives listed. Specify a comma-separated list of drive numbers, the list may include a dash-separated range of drive numbers (e.g., 4,6,8,12-15). 3) Lists each WD drive as firmware is being downloaded to it. WD_download indicates whether the firmware download operation fails or succeeds for each drive. If the firmware download operation succeeds, the drive's model string, serial number, and firmware revision are displayed. 4) After firmware has been downloaded to all of the listed drives, a Firmware Download Summary indicates the number of firmware download operations that succeeded and failed. ============================ WARNING ============================ Be aware that downloading firmware to a drive is a risky operation which could result in a drive being unusable following the download operation. Western Digital STRONGLY recommends that you back up the data on your drives before you execute a firmware download operation. A firmware download operation typically completes within a few seconds per drive; however, it could require a few minutes per drive, depending upon the drive model and its bus type. ============================ The -model Switch ============================ Use the "-model mFile" switch to download firmware (FW) to multiple drive models. "mFile" is the name of an ASCII text file that contains a list of drive models that will have their firmware updated. When you specify "-model mFile", do not specify "fwFilename" in the command line (it will be ignored if it is specified). Each line in "mFile" is a single entry which specifies a Model String, FW Revision, and FW File Name as comma-separated values. One or more Model String entries can be listed in "mFile". The Model String and FW Revision must be entered exactly in order for WD_download to match them (these strings are case sensitive). A Model String entry should look like this (entries must not contain any extraneous whitespace): Model String,FW Revision,FW File Name Where: Model String = indicates which drive model to update FW Revision = update the FW if the drive's current FW does not match this string FW File Name = the name of the file that contains the new firmware Sample Model String Entry: WDC WD800HLFS-50YBU1,04.04V05,wd3456.bin ============================ Configuring WD_download ============================ WD_download uses a configuration file (WD_download.ini) that determines what plug-ins WD_download loads. These plug-ins determine what types of drives WD_download will discover. Refer to the comments in WD_download.ini for details. ============================ Quick Start - Linux ============================ The WD_download executable file that you run on Linux depends upon your Linux installation: the Linux kernel version and the CPU architecture (x86, x64, ARM, etc.). 1) Extract all files from WD_download_VERSION.tgz; a new directory named "WD_download" will be created. 2) To use the CLI (Command Line Interface), use a terminal window to navigate to the extracted directory. 3) Run "./WD_download.sh fwFilename" using the appropriate version of WD_download (replace "fwFilename" with the desired firmware file name). To display help text, type "./WD_download.sh -h" (this will not update firmware on any drives). ============================ Quick Start - Windows ============================ 1) Extract all files from WD_download_VERSION.zip. 2) To use the CLI (Command Line Interface), open a Commmand Prompt window and navigate to the folder where WD_download.exe is located, then run "WD_download fwFilename" (replace "fwFilename" with the appropriate firmware file name). To display help text, type "WD_download -h" or "WD_download" (this will not update firmware on any drives). *** IMPORTANT *** Downloading firmware to a drive requires administrator privilege. On Windows Vista and later releases of Windows (Windows 7, Windows 8, etc.), you should open the Commmand Prompt window with "Run as administrator" privilege. ========================================= Using WD_download on AMCC Cards ========================================= Please edit the WD_download.ini file in the following manner: 1) Comment out the Turquoise plugin list which does not include the tqpl-amcc plugin. 2) Uncomment the Turquoise plugin list which does include the tqpl-amcc plugin. 3) Uncomment the tqpl-amcc portion which states that you agree with the AMCC EULA. ========================================= Using WD_download on MegaRAID Cards ========================================= Please edit the WD_download.ini file in the following manner: 1) Comment out the Turquoise plugin list which does not include the tqpl-storelib plugin. 2) Uncomment the Turquoise plugin list which does include the tqpl-storelib plugin. ================================= Exit Code Description ================================= WD_download's exit code indicates whether the firmware file downloaded successfully to the selected drives. An exit code of zero (0) indicates that the firmware file downloaded successfully to all selected drives. A non-zero exit code indicates that the firmware file failed to download to one or more drives. The exit code is a bit mask, with each bit corresponding to a drive. Bit 1 (the lowest order bit) corresponds to the first selected drive, bit 2 corresponds to the second selected drive, etc. Each drive that has its bit set in the exit code bit mask failed the firmware download. Example: If the firmware download failed on the first and fourth drives, WD_download will return an exit code of 9 (binary 1001). ============================ System Requirements ============================ Linux: - Kernel version 2.6 (minimum) - CPU x86 or x64 - libstdc++.so.5 (if using storelib plugin) or libstdc++.so.6 (if not using storelib plugin) Windows: - Windows XP SP2 32-bit (minimum) or - Windows Vista x64 (minimum) ============================ Usage ============================ Usage: 'WD_download [fwFilename] [-switch] [-switch] ...' All command line switches are optional and case sensitive. Command Line Arguments and Switches: fwFilename The firmware file to download to the WD drives. -batch_mode DO NOT prompt for user input (this switch is provided for batch file execution). Use this switch to download firmware to all discovered drives. Use the '-dev' switch to select specific drives for firmware download. -cfg cFile Configuration file name (default = WD_download.ini). -cs size Set the maximum I/O transfer length (in bytes) specified by 'size' (specify in increments of 512 for ATA drives). -dev devlist Specify a comma-separated list of drive numbers (devlist) that indicates which drives will have firmware downloaded. The 'devlist' may include a dash-separated range of drive numbers (e.g., 4,6,8,12-15), but no spaces. When this switch is specified, you WILL NOT be prompted to select drives for firmware download. -flags bitmask Defines a 'bitmask' of flags to be passed to WD_download. 1 = Perform deferred ATA Download Microcode (works only on drives with FW that supports this feature). -list List the discovered drives and do not download firmware even if 'fwFilename' or '-model mFile' is specified. -model mFile Download firmware to the drive models listed in 'mFile'. -p=ports Scan for drive(s) only on the specified port(s). -sas_mode num Specify the SCSI Write Buffer mode (0 through 31; default is mode 7) for a SAS drive. In most cases, you should not need to specify the sas_mode. Specifying an unsupported value will cause the download operation to fail. -h, -help, -? Display this application's help text. Specify one of these switches instead of the 'fwFilename' argument. ============================ Sample Command Lines ============================ Here are some examples of WD_download command lines. Download firmware file wd1234.bin to the discovered WD drives: WD_download wd1234.bin Download firmware file wd1234.bin to the discovered WD drives; load the configuration file named "wd_dnld.cfg": WD_download wd1234.bin -cfg wd_dnld.cfg List all of the discovered WD drives: WD_download -list Download firmware to drive numbers 4, 6, 8, and 12 through 15: WD_download wd1234.bin -dev 4,6,8,12-15 Download firmware using a 512 byte chunk size WD_download wd1234.bin -cs 512 Download firmware to the drive models listed in "models.txt": WD_download -model models.txt Download firmware to drive number 7 and use the deferred ATA Download Microcode command (the FW will load after the drive is power cycled): WD_download wd1234.bin -dev 7 -flags 1 Download firmware file wd6789.bin to the discovered WD drives using SAS mode 6: WD_download wd6789.bin -sas_mode 6 =============================== Deferred ATA Download Microcode =============================== When you use the "-flags 1" command line switch to download firmware to a drive via the deferred ATA Download Microcode command, the firmware that is currently loaded on the drive must support the deferred ATA Download Microcode command; otherwise, the download operation will fail. The new firmware will load after the drive is power cycled. ============================ Known Issues ============================ Windows: WD_download REQUIRES the ATA Pass Through mechanism to access WD ATA drives (Microsoft's disk driver supports ATA Pass Through operations). If another driver (e.g., from a motherboard driver installation CD) was installed to control the drives, WD_download may not be able to communicate with the drives since some third party vendors' drivers do not support ATA Pass Through operations. Running WD_download requires administrator privilege. On Windows Vista and later releases of Windows (Windows 7, Windows 8, etc.), you should open the Commmand Prompt window with "Run as administrator" privilege before you run WD_download. Windows and Linux: Sometimes, you may need to use the "-cs" command line switch to limit the I/O transfer length in order to successfully download firmware to a drive. For example, the following error message may be displayed on Windows. "FAILURE: ATA_PASS_THROUGH ioctl failed: 87" First try "-cs 512"; if this works, try other I/O transfer lengths to determine the largest I/O transfer length that works. Using a larger I/O transfer length reduces the amount of time required to download firmware. ==============================================================================