
#ifndef DHF_H
#define DHF_H

//   vim:tw=110:ts=4:
/**************************************************************************************************************
*
* FILE   :	DHF.H
*
* DATE	:	$Date: 2004/03/31 18:01:09 $   $Revision: 1.4 $
* Original	:	2004/03/18 16:36:15    Revision: 1.16      Tag: t20040318_02
* Original	:	2004/03/18 09:34:56    Revision: 1.15      Tag: t20040318_01
*
* AUTHOR :	John Meertens
*			Nico Valster
*
* SPECIFICATION: 025726 rev B
*
* DESC   :	structure definitions and function prototypes for unit DHF.
*
*			Customizable via HCFCFG.H, which is included indirectly via HCF.H
*
***************************************************************************************************************
 *
 *
 * SOFTWARE LICENSE
 *
 * This software is provided subject to the following terms and conditions,
 * which you should read carefully before using the software.  Using this
 * software indicates your acceptance of these terms and conditions.  If you do
 * not agree with these terms and conditions, do not use the software.
 *
 * COPYRIGHT © 1994 - 1995	by AT&T.				All Rights Reserved
 * COPYRIGHT © 1999 - 2000 by Lucent Technologies.	All Rights Reserved
 * COPYRIGHT © 2001 - 2004	by Agere Systems Inc.	All Rights Reserved
 * All rights reserved.
 *
 * Redistribution and use in source or binary forms, with or without
 * modifications, are permitted provided that the following conditions are met:
 *
 * . Redistributions of source code must retain the above copyright notice, this
 *    list of conditions and the following Disclaimer as comments in the code as
 *    well as in the documentation and/or other materials provided with the
 *    distribution.
 *
 * . Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following Disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *
 * . Neither the name of Agere Systems Inc. nor the names of the contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * Disclaimer
 *
 * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, INFRINGEMENT AND THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  ANY
 * USE, MODIFICATION OR DISTRIBUTION OF THIS SOFTWARE IS SOLELY AT THE USERS OWN
 * RISK. IN NO EVENT SHALL AGERE SYSTEMS INC. OR CONTRIBUTORS BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, INCLUDING, BUT NOT LIMITED TO, CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 * DAMAGE.
 *
 *
**************************************************************************************************************/


#ifdef _WIN32_WCE
#include <windef.h>
#endif

#include "hcf.h"   		 	// includes HCFCFG.H too

#ifdef DHF_UIL
#define GET_INFO( pp )  uil_get_info( (LTVP)pp )
#define PUT_INFO( pp )  uil_put_info( (LTVP)pp )
#else
#define GET_INFO( pp )  hcf_get_info( ifbp, (LTVP)pp )
#define PUT_INFO( pp )  hcf_put_info( ifbp, (LTVP)pp )
#endif


////////////////////////////// this used to be a separate file: dhfpda.h


#if !((HCF_TYPE) & HCF_TYPE_II)
/* In principle, the max. size of the PDA is is 4096 words. Currently, however, only about 500 bytes of this
 * area are used. To minimize the memory "burden" esp. for DOS-users we claim only 1000 words.
 * Also some of the USB implementations can't handle sizes in excess of 1016 (note that PDA is not actually
 * used in those USB environments (except for some engineering tools), but as a result of common code on
 * higher levels, the PDA is retrieved nonetheless )
 */
#define PDA_SIZE				1000
#define PDA_END 				0x0000   	// End record (contains CRC)
#endif // HCF_TYPE_II


////////////////////////////// this used to be a separate file: dhfpda.h

/*---- Defines --------------------------------------------------------------*/
#define CODEMASK				0x0000FFFFL    	// Codemask for plug records

/*---- Error numbers --------------------------------------------------------*/

#define DHF_ERR_INCOMP_FW		0x40	//Image not compatible with NIC
#define DHF_ERR_DOWNLOAD		0x41	/*download error
										 * PDA CRC not correct
										 * PDA_END record not found
										 * Plug record not found or size mismatch
										 */

/*---- Type definitions -----------------------------------------------------*/

/*
 * Type: 	plugrecord
 *
 * Abstract: This structure represents a Plug Data Record.
 *
 * Description:
 * This structure is used to overlay the plug records in the firmware memory image.
 */

typedef struct {
	hcf_32	code;      	// Code to plug
	hcf_32	addr;      	// Address within the memory image to plug it in
	hcf_32	len;       	// The # of bytes which are available to store it
} plugrecord;

/*
 * Type: memimage
 *
 * Abstract: The "root" description of a complete memory image
 *
 * Description:
 * This type represents an entire memory image. The image is built up of several
 * segments. These segments need not be contiguous areas in memory, in other words
 * the image may contain 'holes'.
 *
 * The 'codep' field points to an array of segment_descriptor structures.
 * The end of the array is indicated by a segment_descriptor of which all fields are zero.
 * The 'execution' field is a 32-bit address representing the execution address
 *	of the firmware within the memory image. This address is zero in case of non-volatile
 *	memory download.
 * The 'compat' field points to an array of TODO
 * 	The end of the array is indicated by a plug record of which all fields are zero.
 * The 'identity' field points to an array of TODO
 * 	The end of the array is indicated by a plug record of which all fields are zero.
 * The Hermes-I specific 'pdaplug' field points to an array of Production Data Plug record structures.
 * 	The end of the array is indicated by a plug record of which all fields are zero.
 * The Hermes-I specific 'priplug' field points to an array of Primary Information Plug record structures.
 * 	The end of the array is indicated by a plug record of which all fields are zero.
 */
typedef struct {
	char					signature[14+1+1];	// signature (see DHF.C) + C/LE-Bin/BE-Bin-flag + format version
	CFG_PROG_STRCT FAR		*codep;			//
	hcf_32           	 	execution;    	// Execution address of the firmware
//#if !((HCF_TYPE) & HCF_TYPE_HII)
	plugrecord FAR       	*pdaplug;     	// Pointer to array of production data
                                       	// plug records
	plugrecord FAR       	*priplug;     	// Pointer to array of primary plug records
//#endif // HCF_TYPE_HII
	CFG_RANGE20_STRCT FAR  	*compat;      	// Pointer to the compatibility info records
	CFG_IDENTITY_STRCT FAR 	*identity;    	// Pointer to the identity info records
} memimage;



/*-----------------------------------------------------------------------------
 *
 * DHF function prototypes
 *
 *---------------------------------------------------------------------------*/

#if HCF_LEGACY_ON
#define dhf_download_firmware( ifbp, dui, pri, fw, type, confirm ) dhf_download_fw( ifbp, fw )
#endif // HCF_LEGACY_ON

EXTERN_C int dhf_download_fw( void *ifbp, memimage *fw );
EXTERN_C int dhf_download_binary( memimage *fw );


/*-----------------------------------------------------------------------------
 *
 * Functions to be provided by the user of the DHF module.
 *
 *---------------------------------------------------------------------------*/

// defined in DHF.C; see there for comments
EXTERN_C hcf_16 *find_record_in_pda( hcf_16 *pdap, hcf_16 code );

#endif  // DHF_H

