wvlan_hcf.c

pcmcia source code

/* This file is part of the Hardware Control Functions Light (HCF-light) library
   to control the Lucent Technologies WaveLAN/IEEE Network I/F Card.
   The HCF is the implementation of the Wireless Connection I/F (WCI).
   
   The HCF-light files are a subset of the HCF files. The complete set offers a
   number of additional facilities, e.g. firmware download, Etherner-II encapsulation,
   additional diagnostic facilities, ASSERT logic to support debugging, 802.11 support,
   Configuration Management.
   This complete set is explicitely not in the Public Domain but can be made 
   available under certain restriction. (see the pointer below for support)
   
   The HCF-light files are free software; you can redistribute it and/or modify it
   under the terms of the GNU General Public License as published by the
   Free Software Foundation; either version 2 of the License, or (at your
   option) any later version.

   This program is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software Foundation,
   Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 
   
   At the time of this writing, you can request for support at:
   [e-mail]
   
   Documentation is expected to be available in the week of 8 Februari 1999

*/


/**************************************************************************************************************
*
* FILE   :	HCF.CPP *************** 2.0 ***********************************************************************
*
* DATE    :	2001/08/17 14:26:32   1.3
*
* AUTHOR :	Nico Valster
*
* DESC   :	HCF Routines hcf_action, hcf_connect, hcf_disable
*						 hcf_disconnect, hcf_download, hcf_enable, hcf_generate_int
*						 hcf_get_info, hcf_get_data, hcf_service_nic
*						 hcf_put_info, hcf_put_data, hcf_register_mailbox, hcf_send,
*						 hcf_send_diag_msg
*			Local Support Routines for above procedures
*
*			Customizable via HCFCFG.H, which is included by HCF.H
*
***************************************************************************************************************
* COPYRIGHT (c) 1995			 by AT&T.	 				All Rights Reserved
* COPYRIGHT (c) 1996, 1997, 1998 by Lucent Technologies.	All Rights Reserved
*
* At the sole discretion of Lucent Technologies parts of this source may be extracted
* and placed in the Public Domain under the GPL.
* This extraction takes place by means of an AWK-script acting on embedded tags.
* The AWK script is:
 *	BEGIN { c = 0 }
 *	{ if ( c == 0 ) i = 1}			#if in @HCF_L>..@HCF_L< block, skip
 *	{ if (name != FILENAME ) name = FILENAME }
 *	
 *	{ if ( i && c == 0  ) { print ; hcf_l_cnt++ } }
 *	#{ if ( i ) { print ; hcf_l_cnt++ } }
 *	#{if ( c == 0 ) { printf("N%d", c) ; hcf_l_cnt++ } }
 *	#{if ( c == 1 ) { printf("E%d", c) ; hcf_l_cnt++ } }
 *	
 *	#END { printf("%s:: HCF lines: %d, HCF_Light lines: %d", name, NR, hcf_l_cnt ) }
*
* and is not in any sense derived from the extracted source. 
*
**************************************************************************************************************/





/****************************************************************************
wvlan_hcf.c,v
Revision 1.3  2001/08/17 14:26:32  root
*** empty log message ***

Revision 1.2  2000/01/06 23:30:52  root
*** empty log message ***

 * 
 *    Rev 1.0   02 Feb 1999 14:32:28   NVALST
 * Initial revision.
Revision 1.3  1999/02/01 22:58:40  nico
*** empty log message ***
 * 
 *    Rev 2.12   29 Jan 1999 10:48:40   NVALST
 * 
 *    Rev 1.108   28 Jan 1999 14:43:18   NVALST
 * intermediate, once more correction of loop in hcf_service_nic + download
 * passed to Marc
 * 
****************************************************************************/

/**************************************************************************************************************
*
* CHANGE HISTORY
*

  960702 - NV
	Original Entry - derived from WaveLAN-I HCF 2.12


*
* ToDo
*
 1:	For all/most functions, update "MSF-accessible fields of Result Block:" entry
 2: Use the "numbered comments" in the NARRATIVE consistently, i.e. hcf_put_info
 3: hcf_put_data, hcf_send, hcf_send_diag_msg
	once the dust is settled whether hcf_put_data or hcf_send is the appropriate place is to specify port,
	it can be considered whether part of the hcf_send_diag_msg and hcf_send can be isolated in a common
	routine.
 4:	hcf_send_diag_msg:
  	- what are the appropriate return values
	- once the dust is settled whether type should or shouldn't be parameter of hcf_send_diag_msg, it can
	  be decided whether the HFX_TX_CNTL_ABS update at each call is needed
 5:	hcf_service_nic, hcf_send, hcf_send_diag_msg etc
 	check for a CONSISTENT strategy for the testing of IFB_CardStat, for presence, enabled, ports
 6:	Decide on the relative merits of HCF_ACT_ASSERT_OFF/_ON versus CFG_REG_MSF_ASSERT
	

*
* Implementation Notes
*
 -	C++ style cast is not used to keep DA-C happy
 -	a leading marker of //! is used. The purpose of such a sequence is to help the
	(maintenance) programmer to understand the flow
 	An example in hcf_action( HCF_ACT_802_3 ) is
	//!		ifbp->IFB_RxFence = 0;
	which is superfluous because IFB_RxFence gets set at every hcf_service_nic but
	it shows to the (maintenance) programmer it is an intentional omission at
	the place where someone could consider it most appropriate at first glance
 -	using near pointers in a model where ss!=ds is an invitation for disaster, so be aware of how you specify
 	your model and how you define variables which are used at interrupt time
 -	Once the comment "the value of -1 for parameter len is meaningless but it guarantees that the next call
 	to bap_ini is interpreted as an initial call, causing the BAP to be really initialized." was considered
 	useful information. Does this trick still lingers somewhere;?
 -	remember that sign extension on 32 bit platforms may cause problems unless code is carefully constructed,
 	e.g. use "(hcf_16)~foo" rather than "~foo"

	
*
* Miscellaneous Notes
*
 -	AccessPoint performance could be improved by adding a hcf_send_pif_msg equivalent of hcf_send_diag_msg


*************************************************************************************************************/

#include "wvlan_hcf.h"				// HCF and MSF common include file
#include "wvlan_hcfdef.h"			// HCF specific include file

/*************************************************************************************************************/
/***************************************  PROTOTYPES  ********************************************************/
/*************************************************************************************************************/
// moving these prototypes to HCFDEF.H turned out to be less attractive in the HCF-light generation
STATIC int			aux_cntl( IFBP ifbp, hcf_16 cmd );
STATIC int			calibrate( IFBP ifbp );
STATIC int			cmd_wait( IFBP ifbp, int cmd_code, int par_0 );
STATIC void			enable_int(IFBP ifbp, int event );
       int			hcf_initialize( IFBP ifbp );
STATIC int			ini_hermes( IFBP ifbp );
STATIC void	 		isr_info( IFBP ifbp );
STATIC int			put_info( IFBP ifbp, LTVP ltvp	);
STATIC hcf_16		alloc( IFBP ifbp, int len );


/**************************************************************************************************************
******************************* D A T A    D E F I N I T I O N S **********************************************
**************************************************************************************************************/

STATIC hcf_8 BASED hcf_rev[] = "\nHCF1.3\n";

/* Note that the "BASED" construction (supposedly) only amounts to something in the small memory model.
 * In that case CS and DS are equal, so we can ignore the consequences of casting the BASED cfg_drv_...
 * structure to hcf_16
 * Note that the whole BASED riggamarole is needlessly complicated because both the Microsoft Compiler and
 * Linker are unnecessary restrictive in what far pointer manipulation they allow
 */


/* 
	The below table accessed via a computed index was the original implementation for hcf_get_info with 
	CFG_DRV_IDENTITY, CFG_DRV_SUP_RANGE, CFG_DRV_ACT_RANGE_PRI, CFG_DRV_ACT_RANGE_STA, CFG_DRV_ACT_RANGE_HSI
	as type. However it was reported that the 68K compiler for MAC OS is unable to initialize pointers.
	Accepting this story at face value, the HCF is coded around this problem by implementing a direct access..
	To save part of the invested effort, the original table is kept as comment.

STATIC LTV_STRCT*   BASED xxxx[ ] = {
	(LTV_STRCT*)&cfg_drv_identity,      //CFG_DRV_IDENTITY              0x0826
	(LTV_STRCT*)&cfg_drv_sup_range,     //CFG_DRV_SUP_RANGE             0x0827
	(LTV_STRCT*)&cfg_drv_act_range_pri, //CFG_DRV_ACT_RANGE_PRI         0x0828
	(LTV_STRCT*)&cfg_drv_act_range_sta  //CFG_DRV_ACT_RANGE_STA         0x0829
	(LTV_STRCT*)&cfg_drv_act_range_hsi	//CFG_DRV_ACT_RANGE_HSI			0x082A
  };
*/


/**************************************************************************************************************
************************** T O P   L E V E L   H C F   R O U T I N E S ****************************************
**************************************************************************************************************/


/*******************************************************************************************************************


.MODULE			hcf_action
.LIBRARY 		HCF
.TYPE 			function
.SYSTEM			msdos
.SYSTEM			NW4
.APPLICATION	Card configuration
.DESCRIPTION	Changes the run-time Card behavior

.ARGUMENTS
  int hcf_action(IFBP ifbp, hcf_action_cmd action )
.RETURNS
  int

  MSF-accessible fields of Result Block: -

.NARRATIVE

 Name:	hcf_action

 Summary: Changes the run-time Card behavior

 Parameters:
  ifbp	address of the Interface Block

  action	number identifying the type of change

  o HCF_ACT_INT_ON		enable interrupt generation by WaveLAN NIC
  o HCF_ACT_INT_OFF		disable interrupt generation by WaveLAN NIC
  o HCF_ACT_CARD_IN		MSF reported Card insertion
  o HCF_ACT_CARD_OUT	MSF reported Card removal

 Returns:
  o	HCF_ACT_INT_OFF
		0: no interrupt pending
		1: interrupt pending
  o	all other
		0 (((however, see the special treatment for HCF_ACT_INT_ON)))

 Remarks:
  o	HCF_ACT_INT_OFF/HCF_ACT_INT_ON codes may be nested but must be balanced. The INT_OFF/INT_ON housekeeping
	is initialized by hcf_connect with a call of hcf_action with INT_OFF, causing the interrupt generation
	mechanism to be disabled at first. This suits MSF implementation based on a polling strategy. An MSFT
	based on a interrupt strategy must call hcf_action with INT_ON in its initialization logic.

  o To prevent I/O while the I/O space is no longer owned by the HCF, due to a card swap, no I/O is allowed
	when the CARD_STAT_PRESENT bit of IFB_CardStat is off.

.DIAGRAM
 2: IFB_IntOffCnt is used to balance the INT_OFF and INT_ON calls.
 4: Disabling of the interrupts is simply achieved by writing a zero to the Hermes IntEn register
 5: To be able to return the information to the MSF whether an interrupt is actually pending, the Hermes
	EvStat register is sampled and compared against the current IFB_IntEnMask value
 6:	Originally the construction "if ( ifbp->IFB_IntOffCnt-- <= 1 )" was used in stead of
 	"if ( --ifbp->IFB_IntOffCnt == 0 )". This serviced to get around the unsigned logic, but as additional
 	"benefit" it seemed the most optimal "fail safe" code (in the sense of shortest/quickest path in error
 	free flows, fail safe in the sense of too many INT_ON invocations compared to INT_OFF). However when a
 	real life MSF programmer ran to a MSF sequence problem, exactly causing that problem, he was annoyed
 	with this fail safe code. As a consequence it is taken out. As a side-effect of this unhappy MSF programmer
 	adventures to find his problem, the return status is defined to reflect the IFBIntOffCnt, Note that this 
 	is solely intended for aid debugging, no MSF logic should depend on this feature, No garuantees for the 
 	future are given.
 	Enabling of the interrupts is achieved by writing the contents of IFB_IntEnMask to the Hermes IntEn
 	register.
 7:	Since the card is present again, it must be re-initialized. Since this may be another card we may as well 
 	clear all bits in IFB_CardStat and set only the "present" bit. 
 	The first call to hcf_enable will restore the contents of HREG_INT_EN register taking the 
 	HCF_ACT_IN_ON/OFF history in account.
 9:	The MSF must call hcf_action with HCF_ACT_CARD_OUT when the MSF detects a card removal (e.g. when the MSF
	is notified by the CAD). As a minimum, the "present" bit in IFB_CardStat must be reset, however since
	the card insertion will clear all other bits, the simplest solution is to clear IFB_CardStat here as well.
	As a result of the resetting of the CARD_STAT_PRESENT bit, no hcf-function except hcf_action with
	HCF_ACT_CARD_IN results in card I/O anymore. However hcf_functions may still perform their other
	activities, e.g. hcf_get_info_mb still supplies a MBIB if one is available.
	As a result of the resetting of the CARD_STAT_INI bit, the call to hcf_initialize by hcf_action with
	HCF_ACT_CARD_IN results in re-initialization of the NIC.
.ENDOC				END DOCUMENTATION


**************************************************************************************************************/
int hcf_action( IFBP ifbp, 					//address of the Interface Block
				hcf_action_cmd action		/*number identifying the type of change
											*/
 				) {

int		rc = HCF_SUCCESS;