drivers/staging/wlags49_h2/dhf.c

   1
   2 //   vim:tw=110:ts=4:
   3 /**************************************************************************************************************
   4 *
   5 * FILE   :      DHF.C
   6 *
   7 * DATE  :       $Date: 2004/07/19 08:16:14 $   $Revision: 1.2 $
   8 * Original      :       2004/05/28 14:05:34    Revision: 1.36      Tag: hcf7_t20040602_01
   9 * Original      :       2004/05/11 06:22:57    Revision: 1.32      Tag: hcf7_t7_20040513_01
  10 * Original      :       2004/04/15 09:24:42    Revision: 1.28      Tag: hcf7_t7_20040415_01
  11 * Original      :       2004/04/08 15:18:16    Revision: 1.27      Tag: t7_20040413_01
  12 * Original      :       2004/04/01 15:32:55    Revision: 1.25      Tag: t7_20040401_01
  13 * Original      :       2004/03/10 15:39:28    Revision: 1.21      Tag: t20040310_01
  14 * Original      :       2004/03/04 11:03:37    Revision: 1.19      Tag: t20040304_01
  15 * Original      :       2004/03/02 09:27:11    Revision: 1.17      Tag: t20040302_03
  16 * Original      :       2004/02/24 13:00:28    Revision: 1.15      Tag: t20040224_01
  17 * Original      :       2004/02/19 10:57:28    Revision: 1.14      Tag: t20040219_01
  18 * Original      :       2003/11/27 09:00:09    Revision: 1.3      Tag: t20021216_01
  19 *
  20 * AUTHOR :      John Meertens
  21 *                       Nico Valster
  22 *
  23 * SPECIFICATION: ........
  24 *
  25 * DESC   :      generic functions to handle the download of NIC firmware
  26 *                       Local Support Routines for above procedures
  27 *
  28 *                       Customizable via HCFCFG.H, which is included by HCF.H
  29 *
  30 *
  31 *       DHF is (intended to be) platform-independent.
  32 *       DHF is a module that provides a number of routines to download firmware
  33 *       images (the names primary, station, access point, secondary and tertiary
  34 *       are used or have been used) to volatile or nonvolatile memory
  35 *       in WaveLAN/IEEE NICs. To achieve this DHF makes use of the WaveLAN/IEEE
  36 *       WCI as implemented by the HCF-module.
  37 *
  38 *       Download to non-volatile memory is used to update a WaveLAN/IEEE NIC to new
  39 *       firmware. Normally this will be an upgrade to newer firmware, although
  40 *       downgrading to older firmware is possible too.
  41 *
  42 * Note: relative to Asserts, the following can be observed:
  43 *       Since the IFB is not known inside the routine, the macro HCFASSERT is replaced with MMDASSERT.
  44 *       Also the line number reported in the assert is raised by FILE_NAME_OFFSET (10000) to discriminate the
  45 *       DHF Asserts from HCF and MMD asserts.
  46 *
  47 ***************************************************************************************************************
  48 *
  49 *
  50 * SOFTWARE LICENSE
  51 *
  52 * This software is provided subject to the following terms and conditions,
  53 * which you should read carefully before using the software.  Using this
  54 * software indicates your acceptance of these terms and conditions.  If you do
  55 * not agree with these terms and conditions, do not use the software.
  56 *
  57 * COPYRIGHT © 1999 - 2000 by Lucent Technologies.       All Rights Reserved
  58 * COPYRIGHT © 2001 - 2004       by Agere Systems Inc.   All Rights Reserved
  59 * All rights reserved.
  60 *
  61 * Redistribution and use in source or binary forms, with or without
  62 * modifications, are permitted provided that the following conditions are met:
  63 *
  64 * . Redistributions of source code must retain the above copyright notice, this
  65 *    list of conditions and the following Disclaimer as comments in the code as
  66 *    well as in the documentation and/or other materials provided with the
  67 *    distribution.
  68 *
  69 * . Redistributions in binary form must reproduce the above copyright notice,
  70 *    this list of conditions and the following Disclaimer in the documentation
  71 *    and/or other materials provided with the distribution.
  72 *
  73 * . Neither the name of Agere Systems Inc. nor the names of the contributors
  74 *    may be used to endorse or promote products derived from this software
  75 *    without specific prior written permission.
  76 *
  77 * Disclaimer
  78 *
  79 * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
  80 * INCLUDING, BUT NOT LIMITED TO, INFRINGEMENT AND THE IMPLIED WARRANTIES OF
  81 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  ANY
  82 * USE, MODIFICATION OR DISTRIBUTION OF THIS SOFTWARE IS SOLELY AT THE USERS OWN
  83 * RISK. IN NO EVENT SHALL AGERE SYSTEMS INC. OR CONTRIBUTORS BE LIABLE FOR ANY
  84 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  85 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  86 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  87 * ON ANY THEORY OF LIABILITY, INCLUDING, BUT NOT LIMITED TO, CONTRACT, STRICT
  88 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  89 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  90 * DAMAGE.
  91 *
  92 *
  93 **************************************************************************************************************/
  94
  95 #include "hcf.h"
  96 #include "hcfdef.h"
  97 #include "dhf.h"
  98 #include "mmd.h"
  99
 100 //to distinguish MMD from HCF asserts by means of line number
 101 #undef  FILE_NAME_OFFSET
 102 #define FILE_NAME_OFFSET MMD_FILE_NAME_OFFSET
 103 /*-----------------------------------------------------------------------------
 104  *
 105  * Defines, data structures, and global variables
 106  *
 107  *---------------------------------------------------------------------------*/
 108
 109 //                    12345678901234
 110 char signature[14] = "FUPU7D37dhfwci";
 111
 112 //The binary download function "relocates" the image using constructions like:
 113 //      fw->identity = (CFG_IDENTITY_STRCT FAR *)((char FAR *)fw->identity + (hcf_32)fw );
 114 //under some of the memory models under MSVC 1.52 these constructions degrade to 16-bits pointer arithmetic.
 115 //fw->identity is limited, such that adding it to fw, does not need to carry over from offset to segment.
 116 //However the segment is not set at all.
 117 //As a workaround the PSEUDO_CHARP macro is introduced which is a char pointer except for MSVC 1.52, in
 118 //which case we know that a 32-bit quantity is adequate as a pointer.
 119 //Note that other platforms may experience comparable problems when using the binary download feature.
 120 #if defined(_MSC_VER) && _MSC_VER ==  800                               // Visual C++ 1.5
 121 #define PSEUDO_CHARP hcf_32
 122 #else
 123 #define PSEUDO_CHARP hcf_8*
 124 #endif
 125
 126 /*-----------------------------------------------------------------------------
 127  *
 128  * LTV-records retrieved from the NIC to:
 129  *      - determine compatibility between NIC and image
 130  *      - ((setup the buffer size dynamically for non-volatile download (see note below) ))
 131  *      - supply plugging information contained in the PDA (H-I only)
 132  *
 133  *---------------------------------------------------------------------------*/
 134
 135 // for USB/H1 we needed a smaller value than the CFG_DL_BUF_STRCT reported 8192
 136 // for the time being it seems simpler to always use 2000 for USB/H1 as well as all other cases rather than
 137 // using the "fixed anyway" CFG_DL_BUF_STRCT.
 138 #define DL_SIZE 2000
 139
 140 //CFG_IDENTITY_STRCT    pri_identity    = { LOF(CFG_IDENTITY_STRCT), CFG_PRI_IDENTITY };
 141 CFG_SUP_RANGE_STRCT     mfi_sup         = { LOF(CFG_SUP_RANGE_STRCT), CFG_NIC_MFI_SUP_RANGE };
 142 CFG_SUP_RANGE_STRCT     cfi_sup         = { LOF(CFG_SUP_RANGE_STRCT), CFG_NIC_CFI_SUP_RANGE };
 143 /* Note: could be used rather than the above explained and defined DL_SIZE if need arises
 144  * CFG_DL_BUF_STRCT     dl_buf          = { LOF(CFG_DL_BUF_STRCT), CFG_DL_BUF };
 145 */
 146
 147 /*-----------------------------------------------------------------------------
 148  * Array ltv_info stores NIC information (in the form of LTV-records)
 149  * needed for download. A NULL record indicates the end of the array.
 150  *---------------------------------------------------------------------------*/
 151
 152 /* The LTV_INFO_STRUCT is needed to save the sizes of the structs, because after a GET_INFO()
 153  * the len field is changed to the real len of the RID by the called routine.
 154  * This is only relevant if the DHF used without reloading the driver/utility.
 155  */
 156
 157 LTV_INFO_STRUCT ltv_info[] = {
 158         { (LTVP)&mfi_sup,                       LOF(CFG_SUP_RANGE_STRCT) } ,
 159         { (LTVP)&cfi_sup,                       LOF(CFG_SUP_RANGE_STRCT) } ,
 160         { (LTVP) NULL,                          0 }
 161 };
 162
 163
 164 /***********************************************************************************************************/
 165 /***************************************  PROTOTYPES  ******************************************************/
 166 /***********************************************************************************************************/
 167 static int                              check_comp_fw( memimage *fw );
 168
 169
 170 /************************************************************************************************************
 171 *.SUBMODULE             int check_comp_fw( memimage *fw )
 172 *.PURPOSE               Checks compatibility of CFI and MFI, NIC as supplier, station/AP firmware image as supplier.
 173 *
 174 *.ARGUMENTS
 175 *   fw          F/W image to be downloaded
 176 *
 177 *.RETURNS
 178 *   HFC_SUCCESS         - firmware OK
 179 *   DHF_ERR_INCOMP_FW
 180 *
 181 *.DESCRIPTION
 182 *   This function uses compatibility and identity information that has been
 183 *   retrieved from the card which is currently inserted to check whether the
 184 *   station firmware image to be downloaded is compatible.
 185 *.ENDDOC                                END DOCUMENTATION
 186 *************************************************************************************************************/
 187 int
 188 check_comp_fw( memimage *fw )
 189 {
 190 CFG_RANGE20_STRCT               *p;
 191 int                                     rc = HCF_SUCCESS;
 192 CFG_RANGE_SPEC_STRCT*   i;
 193
 194         switch( fw->identity->typ ) {
 195           case CFG_FW_IDENTITY:                         //Station F/W
 196           case COMP_ID_FW_AP_FAKE:                      //;?is this useful (used to be:  CFG_AP_IDENTITY)
 197                 break;
 198           default:
 199                 MMDASSERT( DO_ASSERT, fw->identity->typ )       //unknown/unsupported firmware_type:
 200                 rc = DHF_ERR_INCOMP_FW;
 201                 return rc; /* ;? how useful is this anyway,
 202                                         *  till that is sorted out might as well violate my own single exit principle
 203                                         */
 204         }
 205         p = fw->compat;
 206         i = NULL;
 207         while( p->len && i == NULL ) {                                  // check the MFI ranges
 208                 if ( p->typ  == CFG_MFI_ACT_RANGES_STA ) {
 209                         i = mmd_check_comp( (void*)p, &mfi_sup );
 210                 }
 211                 p++;
 212         }
 213         MMDASSERT( i, 0 )       //MFI: NIC Supplier not compatible with F/W image Actor
 214         if ( i ) {
 215                 p = fw->compat;
 216                 i = NULL;
 217                 while ( p->len && i == NULL ) {                 // check the CFI ranges
 218                         if ( p->typ  == CFG_CFI_ACT_RANGES_STA ) {
 219                                  i = mmd_check_comp( (void*)p, &cfi_sup );
 220                         }
 221                         p++;
 222                 }
 223                 MMDASSERT( i, 0 )       //CFI: NIC Supplier not compatible with F/W image Actor
 224         }
 225         if ( i == NULL ) {
 226                 rc = DHF_ERR_INCOMP_FW;
 227         }
 228         return rc;
 229 } // check_comp_fw
 230
 231
 232
 233
 234
 235 /*-----------------------------------------------------------------------------
 236  *
 237  * Exported functions
 238  *
 239  *---------------------------------------------------------------------------*/
 240
 241
 242
 243 /*************************************************************************************************************
 244 *
 245 *.MODULE                int dhf_download_binary( void *ifbp, memimage *fw )
 246 *.PURPOSE               Downloads a complete (primary, station, or access point) firmware image to the NIC.
 247 *
 248 *.ARGUMENTS
 249 *       ifbp            address of the Interface Block
 250 *   fw          F/W image to be downloaded
 251 *
 252 *.RETURNS
 253 *   HCF_SUCCESS                 - download completed successfully.
 254 *   DHF_ERR_INCOMP_FW           - firmware not compatible
 255 *
 256 *.DESCRIPTION
 257 *   Initialize global variables
 258 *   Connect to the DHF
 259 *   Check the compatibility of the image (For primary firmware images it is checked first
 260 *       whether download is necessary).
 261 *   If everything's download the firmware.
 262 *   Disconnect from the DHF.
 263 *
 264 *
 265 *.DIAGRAM
 266 *
 267 *.NOTICE:
 268         MMDASSERT is unacceptable because some drivers call dhf_download_binary before hcf_connect
 269
 270 * The old comment was:
 271 *.ENDDOC                                END DOCUMENTATION
 272 *************************************************************************************************************/
 273 int
 274 dhf_download_binary( memimage *fw )
 275 {
 276 int                     rc = HCF_SUCCESS;
 277 CFG_PROG_STRCT  *p;
 278 int                             i;
 279
 280         //validate the image
 281         for ( i = 0; i < sizeof(signature) && fw->signature[i] == signature[i]; i++ ) /*NOP*/;
 282         if ( i != sizeof(signature)             ||
 283                  fw->signature[i] != 0x01       ||
 284                  //test for Little/Big Endian Binary flag
 285                  fw->signature[i+1] != ( /*HCF_BIG_ENDIAN ? 'B' : */ 'L' ) ) rc = DHF_ERR_INCOMP_FW;
 286         else {                                  //Little Endian Binary format
 287                 fw->codep    = (CFG_PROG_STRCT FAR *)((PSEUDO_CHARP)fw->codep + (hcf_32)fw );
 288                 fw->identity = (CFG_IDENTITY_STRCT FAR *)((PSEUDO_CHARP)fw->identity + (hcf_32)fw );
 289                 fw->compat   = (CFG_RANGE20_STRCT FAR *)((PSEUDO_CHARP)fw->compat + (hcf_32)fw );
 290                 for ( i = 0; fw->p[i]; i++ ) fw->p[i] = ((PSEUDO_CHARP)fw->p[i] + (hcf_32)fw );
 291                 p = fw->codep;
 292                 while ( p->len ) {
 293                         p->host_addr = (PSEUDO_CHARP)p->host_addr + (hcf_32)fw;
 294                         p++;
 295                 }
 296         }
 297         return rc;
 298 }   // dhf_download_binary
 299
 300
 301 /*************************************************************************************************************
 302 *
 303 *.MODULE                int dhf_download_fw( void *ifbp, memimage *fw )
 304 *.PURPOSE               Downloads a complete (primary or tertiary) firmware image to the NIC.
 305 *
 306 *.ARGUMENTS
 307 *       ifbp            address of the Interface Block
 308 *   fw                  F/W image to be downloaded
 309 *
 310 *.RETURNS
 311 *       HCF_SUCCESS             - download completed successfully.
 312 *       HCF_ERR_NO_NIC          - no NIC present
 313 *       DHF_ERR_INCOMP_FW       - firmware not compatible
 314 *
 315 *.DESCRIPTION
 316 * - check the signature of the image
 317 * - get the compatibility information from the components on the NIC
 318 *         - Primary Firmware Identity
 319 *         -     Modem - Firmware I/F
 320 *         -     Controller - Firmware I/F
 321 *!! - if necessary ( i.e. H-I) get the PDA contents from the NIC
 322 * - check the compatibility of the MFI and CFI of the NIC with the F/W image
 323 *       Note: the Primary F/W compatibility is only relevant for the "running" HCF and is already verified in
 324 *       hcf_connect
 325 *!! -   if necessary ( i.e. H-I)
 326 *!!       -     verify the sumcheck of the PDA
 327 *!!       -     plug the image (based on the PDA and the default plug records)
 328 * - loop over all the download LTVs in the image which consists of a sequence of
 329 *         - CFG_PROG_VOLATILE/CFG_PROG_NON_VOLATILE
 330 *         - 1 or more sequences of CFG_PROG_ADDR, CFG_PROG_DATA,....,CFG_PROG_DATA
 331 *         -     CFG_PROG_STOP
 332 *
 333 *.DIAGRAM
 334 *
 335 *.NOTICE
 336 * The old comment was:
 337 *       // Download primary firmware if necessary and allowed. This is done silently (without telling
 338 *       // the user) and only if the firmware in the download image is newer than the firmware in the
 339 *       // card.  In Major version 4 of the primary firmware functions of Hermes and Shark were
 340 *       // combined. Prior to that two separate versions existed. We only have to download primary
 341 *       // firmware if major version of primary firmware in the NIC < 4.
 342 *       //              download = pri_identity.version_major < 4;
 343 *       //              if ( download ) {
 344 *       //                      rc = check_comp_primary( fw );
 345 *       //              }
 346 * It is my understanding that Pri Variant 1 must be updated by Pri Variant 2. The test on
 347 * major version < 4 should amount to the same result but be "principally" less correct
 348 * In deliberation with the Architecture team, it was decided that this upgrade for old H-I
 349 * NICs, is an aspect which belongs on the WSU level not on the DHF level
 350 *
 351 *.ENDDOC                                END DOCUMENTATION
 352 *************************************************************************************************************/
 353 int
 354 dhf_download_fw( void *ifbp, memimage *fw )
 355 {
 356 int                             rc = HCF_SUCCESS;
 357 LTV_INFO_STRUCT_PTR pp = ltv_info;
 358 CFG_PROG_STRCT          *p = fw->codep;
 359 LTVP                            ltvp;
 360 int                                     i;
 361
 362         MMDASSERT( fw != NULL, 0 )
 363         //validate the image
 364         for ( i = 0; i < sizeof(signature) && fw->signature[i] == signature[i]; i++ ) /*NOP*/;
 365         if ( i != sizeof(signature)             ||
 366                  fw->signature[i] != 0x01               ||
 367                  //check for binary image
 368                  ( fw->signature[i+1] != 'C' && fw->signature[i+1] != ( /*HCF_BIG_ENDIAN ? 'B' : */ 'L' ) ) )
 369                  rc = DHF_ERR_INCOMP_FW;
 370
 371 //      Retrieve all information needed for download from the NIC
 372         while ( ( rc == HCF_SUCCESS ) && ( ( ltvp = pp->ltvp) != NULL ) ) {
 373                 ltvp->len = pp++->len;  // Set len to original len. This len is changed to real len by GET_INFO()
 374                 rc = GET_INFO( ltvp );
 375                 MMDASSERT( rc == HCF_SUCCESS, rc )
 376                 MMDASSERT( rc == HCF_SUCCESS, ltvp->typ )
 377                 MMDASSERT( rc == HCF_SUCCESS, ltvp->len )
 378         }
 379         if ( rc == HCF_SUCCESS ) rc = check_comp_fw( fw );
 380         if ( rc == HCF_SUCCESS ) {
 381                 while ( rc == HCF_SUCCESS && p->len ) {
 382                         rc = PUT_INFO( p );
 383                         p++;
 384                 }
 385         }
 386         MMDASSERT( rc == HCF_SUCCESS, rc )
 387         return rc;
 388 }   // dhf_download_fw
 389
 390