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 (C) 1999 - 2000 by Lucent Technologies.     All Rights Reserved
  58 * COPYRIGHT (C) 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 /*-----------------------------------------------------------------------------
 113  *
 114  * LTV-records retrieved from the NIC to:
 115  *      - determine compatibility between NIC and image
 116  *      - ((setup the buffer size dynamically for non-volatile download (see note below) ))
 117  *      - supply plugging information contained in the PDA (H-I only)
 118  *
 119  *---------------------------------------------------------------------------*/
 120
 121 /* for USB/H1 we needed a smaller value than the CFG_DL_BUF_STRCT reported 8192
 122         for the time being it seems simpler to always use 2000 for USB/H1 as well as all other cases rather than
 123         using the "fixed anyway" CFG_DL_BUF_STRCT. */
 124 #define DL_SIZE 2000
 125
 126 /* CFG_IDENTITY_STRCT           pri_identity    = { LOF(CFG_IDENTITY_STRCT), CFG_PRI_IDENTITY }; */
 127 CFG_SUP_RANGE_STRCT     mfi_sup         = { LOF(CFG_SUP_RANGE_STRCT), CFG_NIC_MFI_SUP_RANGE };
 128 CFG_SUP_RANGE_STRCT     cfi_sup         = { LOF(CFG_SUP_RANGE_STRCT), CFG_NIC_CFI_SUP_RANGE };
 129 /* Note: could be used rather than the above explained and defined DL_SIZE if need arises
 130  * CFG_DL_BUF_STRCT     dl_buf          = { LOF(CFG_DL_BUF_STRCT), CFG_DL_BUF };
 131 */
 132
 133 /*-----------------------------------------------------------------------------
 134  * Array ltv_info stores NIC information (in the form of LTV-records)
 135  * needed for download. A NULL record indicates the end of the array.
 136  *---------------------------------------------------------------------------*/
 137
 138 /* The LTV_INFO_STRUCT is needed to save the sizes of the structs, because after a GET_INFO()
 139  * the len field is changed to the real len of the RID by the called routine.
 140  * This is only relevant if the DHF used without reloading the driver/utility.
 141  */
 142
 143 LTV_INFO_STRUCT ltv_info[] = {
 144         { (LTVP)&mfi_sup,                       LOF(CFG_SUP_RANGE_STRCT) } ,
 145         { (LTVP)&cfi_sup,                       LOF(CFG_SUP_RANGE_STRCT) } ,
 146         { (LTVP) NULL,                          0 }
 147 };
 148
 149
 150 /***********************************************************************************************************/
 151 /***************************************  PROTOTYPES  ******************************************************/
 152 /***********************************************************************************************************/
 153 static int                              check_comp_fw(memimage *fw);
 154
 155
 156 /************************************************************************************************************
 157 *.SUBMODULE             int check_comp_fw( memimage *fw )
 158 *.PURPOSE               Checks compatibility of CFI and MFI, NIC as supplier, station/AP firmware image as supplier.
 159 *
 160 *.ARGUMENTS
 161 *   fw          F/W image to be downloaded
 162 *
 163 *.RETURNS
 164 *   HFC_SUCCESS         - firmware OK
 165 *   DHF_ERR_INCOMP_FW
 166 *
 167 *.DESCRIPTION
 168 *   This function uses compatibility and identity information that has been
 169 *   retrieved from the card which is currently inserted to check whether the
 170 *   station firmware image to be downloaded is compatible.
 171 *.ENDDOC                                END DOCUMENTATION
 172 *************************************************************************************************************/
 173 int
 174 check_comp_fw(memimage *fw)
 175 {
 176 CFG_RANGE20_STRCT               *p;
 177 int                                     rc = HCF_SUCCESS;
 178 CFG_RANGE_SPEC_STRCT *i;
 179
 180         switch (fw->identity->typ) {
 181         case CFG_FW_IDENTITY:                           /* Station F/W */
 182         case COMP_ID_FW_AP_FAKE:                        /* ;?is this useful (used to be:  CFG_AP_IDENTITY) */
 183                 break;
 184         default:
 185                 MMDASSERT(DO_ASSERT, fw->identity->typ)         /* unknown/unsupported firmware_type: */
 186                 rc = DHF_ERR_INCOMP_FW;
 187                 return rc; /* ;? how useful is this anyway,
 188                                         *  till that is sorted out might as well violate my own single exit principle
 189                                         */
 190         }
 191         p = fw->compat;
 192         i = NULL;
 193         while (p->len && i == NULL) {                                   /* check the MFI ranges */
 194                 if (p->typ  == CFG_MFI_ACT_RANGES_STA) {
 195                         i = mmd_check_comp((void *)p, &mfi_sup);
 196                 }
 197                 p++;
 198         }
 199         MMDASSERT(i, 0) /* MFI: NIC Supplier not compatible with F/W image Actor */
 200         if (i) {
 201                 p = fw->compat;
 202                 i = NULL;
 203                 while (p->len && i == NULL) {                   /* check the CFI ranges */
 204                         if (p->typ  == CFG_CFI_ACT_RANGES_STA) {
 205                                  i = mmd_check_comp((void *)p, &cfi_sup);
 206                         }
 207                         p++;
 208                 }
 209                 MMDASSERT(i, 0) /* CFI: NIC Supplier not compatible with F/W image Actor */
 210         }
 211         if (i == NULL) {
 212                 rc = DHF_ERR_INCOMP_FW;
 213         }
 214         return rc;
 215 } /* check_comp_fw */
 216
 217
 218
 219
 220
 221 /*-----------------------------------------------------------------------------
 222  *
 223  * Exported functions
 224  *
 225  *---------------------------------------------------------------------------*/
 226
 227
 228
 229 /*************************************************************************************************************
 230 *
 231 *.MODULE                int dhf_download_binary( void *ifbp, memimage *fw )
 232 *.PURPOSE               Downloads a complete (primary, station, or access point) firmware image to the NIC.
 233 *
 234 *.ARGUMENTS
 235 *       ifbp            address of the Interface Block
 236 *   fw          F/W image to be downloaded
 237 *
 238 *.RETURNS
 239 *   HCF_SUCCESS                 - download completed successfully.
 240 *   DHF_ERR_INCOMP_FW           - firmware not compatible
 241 *
 242 *.DESCRIPTION
 243 *   Initialize global variables
 244 *   Connect to the DHF
 245 *   Check the compatibility of the image (For primary firmware images it is checked first
 246 *       whether download is necessary).
 247 *   If everything's download the firmware.
 248 *   Disconnect from the DHF.
 249 *
 250 *
 251 *.DIAGRAM
 252 *
 253 *.NOTICE:
 254         MMDASSERT is unacceptable because some drivers call dhf_download_binary before hcf_connect
 255
 256 * The old comment was:
 257 *.ENDDOC                                END DOCUMENTATION
 258 *************************************************************************************************************/
 259 int
 260 dhf_download_binary(memimage *fw)
 261 {
 262 int                     rc = HCF_SUCCESS;
 263 CFG_PROG_STRCT  *p;
 264 int                             i;
 265
 266         /* validate the image */
 267         for (i = 0; i < sizeof(signature) && fw->signature[i] == signature[i]; i++)
 268                 ; /* NOP */
 269         if (i != sizeof(signature)              ||
 270                  fw->signature[i] != 0x01       ||
 271                  /* test for Little/Big Endian Binary flag */
 272                  fw->signature[i+1] != (/* HCF_BIG_ENDIAN ? 'B' : */ 'L'))
 273                 rc = DHF_ERR_INCOMP_FW;
 274         else {                                  /* Little Endian Binary format */
 275                 fw->codep    = (CFG_PROG_STRCT FAR*)((char *)fw->codep + (hcf_32)fw);
 276                 fw->identity = (CFG_IDENTITY_STRCT FAR*)((char *)fw->identity + (hcf_32)fw);
 277                 fw->compat   = (CFG_RANGE20_STRCT FAR*)((char *)fw->compat + (hcf_32)fw);
 278                 for (i = 0; fw->p[i]; i++)
 279                         fw->p[i] = ((char *)fw->p[i] + (hcf_32)fw);
 280                 p = fw->codep;
 281                 while (p->len) {
 282                         p->host_addr = (char *)p->host_addr + (hcf_32)fw;
 283                         p++;
 284                 }
 285         }
 286         return rc;
 287 }   /* dhf_download_binary */
 288
 289
 290 /*************************************************************************************************************
 291 *
 292 *.MODULE                int dhf_download_fw( void *ifbp, memimage *fw )
 293 *.PURPOSE               Downloads a complete (primary or tertiary) firmware image to the NIC.
 294 *
 295 *.ARGUMENTS
 296 *       ifbp            address of the Interface Block
 297 *   fw                  F/W image to be downloaded
 298 *
 299 *.RETURNS
 300 *       HCF_SUCCESS             - download completed successfully.
 301 *       HCF_ERR_NO_NIC          - no NIC present
 302 *       DHF_ERR_INCOMP_FW       - firmware not compatible
 303 *
 304 *.DESCRIPTION
 305 * - check the signature of the image
 306 * - get the compatibility information from the components on the NIC
 307 *         - Primary Firmware Identity
 308 *         -     Modem - Firmware I/F
 309 *         -     Controller - Firmware I/F
 310 *!! - if necessary ( i.e. H-I) get the PDA contents from the NIC
 311 * - check the compatibility of the MFI and CFI of the NIC with the F/W image
 312 *       Note: the Primary F/W compatibility is only relevant for the "running" HCF and is already verified in
 313 *       hcf_connect
 314 *!! -   if necessary ( i.e. H-I)
 315 *!!       -     verify the sumcheck of the PDA
 316 *!!       -     plug the image (based on the PDA and the default plug records)
 317 * - loop over all the download LTVs in the image which consists of a sequence of
 318 *         - CFG_PROG_VOLATILE/CFG_PROG_NON_VOLATILE
 319 *         - 1 or more sequences of CFG_PROG_ADDR, CFG_PROG_DATA,....,CFG_PROG_DATA
 320 *         -     CFG_PROG_STOP
 321 *
 322 *.DIAGRAM
 323 *
 324 *.NOTICE
 325 * The old comment was:
 326 *       // Download primary firmware if necessary and allowed. This is done silently (without telling
 327 *       // the user) and only if the firmware in the download image is newer than the firmware in the
 328 *       // card.  In Major version 4 of the primary firmware functions of Hermes and Shark were
 329 *       // combined. Prior to that two separate versions existed. We only have to download primary
 330 *       // firmware if major version of primary firmware in the NIC < 4.
 331 *       //              download = pri_identity.version_major < 4;
 332 *       //              if ( download ) {
 333 *       //                      rc = check_comp_primary( fw );
 334 *       //              }
 335 * It is my understanding that Pri Variant 1 must be updated by Pri Variant 2. The test on
 336 * major version < 4 should amount to the same result but be "principally" less correct
 337 * In deliberation with the Architecture team, it was decided that this upgrade for old H-I
 338 * NICs, is an aspect which belongs on the WSU level not on the DHF level
 339 *
 340 *.ENDDOC                                END DOCUMENTATION
 341 *************************************************************************************************************/
 342 int
 343 dhf_download_fw(void *ifbp, memimage *fw)
 344 {
 345 int                             rc = HCF_SUCCESS;
 346 LTV_INFO_STRUCT_PTR pp = ltv_info;
 347 CFG_PROG_STRCT          *p = fw->codep;
 348 LTVP                            ltvp;
 349 int                                     i;
 350
 351         MMDASSERT(fw != NULL, 0)
 352         /* validate the image */
 353         for (i = 0; i < sizeof(signature) && fw->signature[i] == signature[i]; i++)
 354                 ; /* NOP */
 355         if (i != sizeof(signature)              ||
 356                  fw->signature[i] != 0x01               ||
 357                  /* check for binary image */
 358                  (fw->signature[i+1] != 'C' && fw->signature[i+1] != (/*HCF_BIG_ENDIAN ? 'B' : */ 'L')))
 359                  rc = DHF_ERR_INCOMP_FW;
 360
 361 /*      Retrieve all information needed for download from the NIC */
 362         while ((rc == HCF_SUCCESS) && ((ltvp = pp->ltvp) != NULL)) {
 363                 ltvp->len = pp++->len;  /* Set len to original len. This len is changed to real len by GET_INFO() */
 364                 rc = GET_INFO(ltvp);
 365                 MMDASSERT(rc == HCF_SUCCESS, rc)
 366                 MMDASSERT(rc == HCF_SUCCESS, ltvp->typ)
 367                 MMDASSERT(rc == HCF_SUCCESS, ltvp->len)
 368         }
 369         if (rc == HCF_SUCCESS)
 370                 rc = check_comp_fw(fw);
 371         if (rc == HCF_SUCCESS) {
 372                 while (rc == HCF_SUCCESS && p->len) {
 373                         rc = PUT_INFO(p);
 374                         p++;
 375                 }
 376         }
 377         MMDASSERT(rc == HCF_SUCCESS, rc)
 378         return rc;
 379 }   /* dhf_download_fw */
 380
 381