3 /**************************************************************************************************************
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
20 * AUTHOR : John Meertens
23 * SPECIFICATION: ........
25 * DESC : generic functions to handle the download of NIC firmware
26 * Local Support Routines for above procedures
28 * Customizable via HCFCFG.H, which is included by HCF.H
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.
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.
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.
47 ***************************************************************************************************************
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.
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.
61 * Redistribution and use in source or binary forms, with or without
62 * modifications, are permitted provided that the following conditions are met:
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
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.
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.
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
93 **************************************************************************************************************/
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 /*-----------------------------------------------------------------------------
105 * Defines, data structures, and global variables
107 *---------------------------------------------------------------------------*/
110 char signature
[14] = "FUPU7D37dhfwci";
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
123 #define PSEUDO_CHARP (hcf_8 *)
126 /*-----------------------------------------------------------------------------
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)
133 *---------------------------------------------------------------------------*/
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. */
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 };
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 *---------------------------------------------------------------------------*/
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.
157 LTV_INFO_STRUCT ltv_info
[] = {
158 { (LTVP
)&mfi_sup
, LOF(CFG_SUP_RANGE_STRCT
) } ,
159 { (LTVP
)&cfi_sup
, LOF(CFG_SUP_RANGE_STRCT
) } ,
164 /***********************************************************************************************************/
165 /*************************************** PROTOTYPES ******************************************************/
166 /***********************************************************************************************************/
167 static int check_comp_fw(memimage
*fw
);
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.
175 * fw F/W image to be downloaded
178 * HFC_SUCCESS - firmware OK
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 *************************************************************************************************************/
188 check_comp_fw(memimage
*fw
)
190 CFG_RANGE20_STRCT
*p
;
191 int rc
= HCF_SUCCESS
;
192 CFG_RANGE_SPEC_STRCT
*i
;
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) */
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
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
);
213 MMDASSERT(i
, 0) /* MFI: NIC Supplier not compatible with F/W image Actor */
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
);
223 MMDASSERT(i
, 0) /* CFI: NIC Supplier not compatible with F/W image Actor */
226 rc
= DHF_ERR_INCOMP_FW
;
229 } /* check_comp_fw */
235 /*-----------------------------------------------------------------------------
239 *---------------------------------------------------------------------------*/
243 /*************************************************************************************************************
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.
249 * ifbp address of the Interface Block
250 * fw F/W image to be downloaded
253 * HCF_SUCCESS - download completed successfully.
254 * DHF_ERR_INCOMP_FW - firmware not compatible
257 * Initialize global variables
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.
268 MMDASSERT is unacceptable because some drivers call dhf_download_binary before hcf_connect
270 * The old comment was:
271 *.ENDDOC END DOCUMENTATION
272 *************************************************************************************************************/
274 dhf_download_binary(memimage
*fw
)
276 int rc
= HCF_SUCCESS
;
280 /* validate the image */
281 for (i
= 0; i
< sizeof(signature
) && fw
->signature
[i
] == signature
[i
]; i
++)
283 if (i
!= sizeof(signature
) ||
284 fw
->signature
[i
] != 0x01 ||
285 /* test for Little/Big Endian Binary flag */
286 fw
->signature
[i
+1] != (/* HCF_BIG_ENDIAN ? 'B' : */ 'L'))
287 rc
= DHF_ERR_INCOMP_FW
;
288 else { /* Little Endian Binary format */
289 fw
->codep
= (CFG_PROG_STRCT FAR
*)((PSEUDO_CHARP
)fw
->codep
+ (hcf_32
)fw
);
290 fw
->identity
= (CFG_IDENTITY_STRCT FAR
*)((PSEUDO_CHARP
)fw
->identity
+ (hcf_32
)fw
);
291 fw
->compat
= (CFG_RANGE20_STRCT FAR
*)((PSEUDO_CHARP
)fw
->compat
+ (hcf_32
)fw
);
292 for (i
= 0; fw
->p
[i
]; i
++)
293 fw
->p
[i
] = ((PSEUDO_CHARP
)fw
->p
[i
] + (hcf_32
)fw
);
296 p
->host_addr
= (PSEUDO_CHARP
)p
->host_addr
+ (hcf_32
)fw
;
301 } /* dhf_download_binary */
304 /*************************************************************************************************************
306 *.MODULE int dhf_download_fw( void *ifbp, memimage *fw )
307 *.PURPOSE Downloads a complete (primary or tertiary) firmware image to the NIC.
310 * ifbp address of the Interface Block
311 * fw F/W image to be downloaded
314 * HCF_SUCCESS - download completed successfully.
315 * HCF_ERR_NO_NIC - no NIC present
316 * DHF_ERR_INCOMP_FW - firmware not compatible
319 * - check the signature of the image
320 * - get the compatibility information from the components on the NIC
321 * - Primary Firmware Identity
322 * - Modem - Firmware I/F
323 * - Controller - Firmware I/F
324 *!! - if necessary ( i.e. H-I) get the PDA contents from the NIC
325 * - check the compatibility of the MFI and CFI of the NIC with the F/W image
326 * Note: the Primary F/W compatibility is only relevant for the "running" HCF and is already verified in
328 *!! - if necessary ( i.e. H-I)
329 *!! - verify the sumcheck of the PDA
330 *!! - plug the image (based on the PDA and the default plug records)
331 * - loop over all the download LTVs in the image which consists of a sequence of
332 * - CFG_PROG_VOLATILE/CFG_PROG_NON_VOLATILE
333 * - 1 or more sequences of CFG_PROG_ADDR, CFG_PROG_DATA,....,CFG_PROG_DATA
339 * The old comment was:
340 * // Download primary firmware if necessary and allowed. This is done silently (without telling
341 * // the user) and only if the firmware in the download image is newer than the firmware in the
342 * // card. In Major version 4 of the primary firmware functions of Hermes and Shark were
343 * // combined. Prior to that two separate versions existed. We only have to download primary
344 * // firmware if major version of primary firmware in the NIC < 4.
345 * // download = pri_identity.version_major < 4;
346 * // if ( download ) {
347 * // rc = check_comp_primary( fw );
349 * It is my understanding that Pri Variant 1 must be updated by Pri Variant 2. The test on
350 * major version < 4 should amount to the same result but be "principally" less correct
351 * In deliberation with the Architecture team, it was decided that this upgrade for old H-I
352 * NICs, is an aspect which belongs on the WSU level not on the DHF level
354 *.ENDDOC END DOCUMENTATION
355 *************************************************************************************************************/
357 dhf_download_fw(void *ifbp
, memimage
*fw
)
359 int rc
= HCF_SUCCESS
;
360 LTV_INFO_STRUCT_PTR pp
= ltv_info
;
361 CFG_PROG_STRCT
*p
= fw
->codep
;
365 MMDASSERT(fw
!= NULL
, 0)
366 /* validate the image */
367 for (i
= 0; i
< sizeof(signature
) && fw
->signature
[i
] == signature
[i
]; i
++)
369 if (i
!= sizeof(signature
) ||
370 fw
->signature
[i
] != 0x01 ||
371 /* check for binary image */
372 (fw
->signature
[i
+1] != 'C' && fw
->signature
[i
+1] != (/*HCF_BIG_ENDIAN ? 'B' : */ 'L')))
373 rc
= DHF_ERR_INCOMP_FW
;
375 /* Retrieve all information needed for download from the NIC */
376 while ((rc
== HCF_SUCCESS
) && ((ltvp
= pp
->ltvp
) != NULL
)) {
377 ltvp
->len
= pp
++->len
; /* Set len to original len. This len is changed to real len by GET_INFO() */
379 MMDASSERT(rc
== HCF_SUCCESS
, rc
)
380 MMDASSERT(rc
== HCF_SUCCESS
, ltvp
->typ
)
381 MMDASSERT(rc
== HCF_SUCCESS
, ltvp
->len
)
383 if (rc
== HCF_SUCCESS
)
384 rc
= check_comp_fw(fw
);
385 if (rc
== HCF_SUCCESS
) {
386 while (rc
== HCF_SUCCESS
&& p
->len
) {
391 MMDASSERT(rc
== HCF_SUCCESS
, rc
)
393 } /* dhf_download_fw */