wvlan_hcf.c

pcmcia source code

	be called not only at the transition from disabled to enabled but whenever a port is enabled.
12:	When the port successfully changes from disabled to enabled - including the case when no NIC is
	present - , the NIC status as reflected by IFB_CardStat must change to enabled

.DIAGRAM

.NOTICE
  When the Hermes enable cmd is given, the static configuration of the Hermes is done.
.ENDOC				END DOCUMENTATION

-------------------------------------------------------------------------------------------------------------*/
int hcf_enable( IFBP ifbp, hcf_16 port ) {

int	rc;


	
	if ( (ifbp->IFB_CardStat & CARD_STAT_PRESENT) == 0 
	   ) { rc = HCF_ERR_NO_NIC;	}	/* 6 */
	else {
		rc = HCF_SUCCESS;
			rc = cmd_wait( ifbp, HCMD_ENABLE | ( port << 8 ), 0 );
			if ( rc == HCF_SUCCESS ) enable_int( ifbp, HREG_EV_INFO | HREG_EV_RX | HREG_EV_ALLOC );		/* 8 */
	}
	if ( rc == HCF_SUCCESS || rc == HCF_ERR_NO_NIC ) {
		ifbp->IFB_CardStat |= CARD_STAT_ENABLED;
	}
	return rc;

}/* hcf_enable */



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


.MODULE			hcf_get_data
.LIBRARY 		HCF
.TYPE 			function
.SYSTEM			msdos
.SYSTEM			unix
.APPLICATION	Data Transfer Function for WaveLAN based drivers and utilities
.DESCRIPTION
	Obtains received message data parts from NIC RAM
.ARGUMENTS
	int hcf_get_data( IFBP ifbp, int offset, wci_bufp bufp, int len )
	Card Interrupts disabled
.RETURNS
	hcf_16
		zero			NIC not removed during data copying process
		HCF_ERR_NO_NIC	NIC removed during data copying process
		......

  MSF-accessible fields of Result Block: -

.NARRATIVE
	parameters:
		ifbp		address of the Interface Block
		offset		offset (in bytes) in buffer in NIC RAM to start copy process
		len			length (in bytes) of data to be copied
		bufp		char pointer, address of buffer in PC RAM

	When hcf_service_nic reports the availability of data, hcf_get_data can be
	called to copy that data from NIC RAM to PC RAM.

	Hcf_get_data copies the number of bytes requested by the parameter len from
	NIC RAM to PC RAM. If len is larger than the (remaining) length of the
	message, undefined data is appended to the message. This implies that if
	hcf_get_data is called while the last hcf_service_nic reported no data
	available, undefined data is copied.

	Hcf_get_data starts the copy process at the offset requested by the
	parameter offset, e.g. offset HFS_ADDR_DEST will start copying from the
	Destination Address, the very begin of the 802.3 framemessage.
	In case of a fragmented PC RAM buffer, it is the responsibility of the MSF,
	to specify as offset the cumulative values of the len parameters of the
	preceeding hcf_get_data calls. This I/F gives a MSF the facility to read
	(part of) a message and then read it again.
	
.DIAGRAM
.ENDOC				END DOCUMENTATION


-------------------------------------------------------------------------------------------------------------*/
int hcf_get_data( IFBP ifbp, int offset, wci_bufp bufp, int len ) {

int rc = HCF_SUCCESS;
//int	tlen;


	if ( ifbp->IFB_CardStat & CARD_STAT_PRESENT ) {	
		if ( offset < 0 ) offset -= HFS_STAT;
		else {
			offset += ifbp->IFB_FSBase;
	    }
		if ( rc == HCF_SUCCESS ) rc = hcfio_string( ifbp, BAP_1, ifbp->IFB_RxFID, offset, bufp, 0, len, IO_IN );
	}
	return rc;
}/* hcf_get_data */




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


 Name:	hcf_get_info

 Summary: Obtains transient and persistent configuration information from the
	Card and from the HCF

 Parameters:
  ifbp	address of the Interface Block

  ltvp	address of LengthTypeValue structure specifying the "what" and the "how much" of the information
  		to be collected from the HCF or from the Hermes

 Returns:
	int
		..... ????????????????	

 Remarks: Transfers operation information and transient and persistent
 	configuration information from the Card and from the HCF to the MSF.
	The exact layout of the provided data structure
	depends on the action code. Copying stops if either the complete
	Configuration Information is copied or if the number of bytes indicated
	by len is copied.  Len acts as a safe guard against Configuration
	Information blocks which have different sizes for different Hermes
	versions, e.g. when later versions support more tallies than earlier
	versions. It is a consious decision that unused parts of the PC RAM buffer are not cleared.

 Remarks: The only error against which is protected is the "Read error"
	as result of Card removal. Only the last hcf_io_string need
	to be protected because if the first fails the second will fail
	as well. Checking for cmd_wait errors is supposed superfluous because
	problems in cmd_wait are already caught or will be caught by
	hcf_enable.
	
	
 3:	tallying of "No inquire space" is done by cmd_wait

 Note:
	the codes for type are "cleverly" chosen to be identical to the RID
	

 7:	The return status of cmd_wait and the first hcfio_in_string can be ignored, because when one fails, the
 	other fails via the IFB_TimStat mechanism
		
**************************************************************************************************************/
int hcf_get_info(IFBP ifbp, LTVP ltvp ) {

int				rc = HCF_ERR_LEN;
//hcf_io			reg;
hcf_16			i, len;
hcf_16			type;						//don't change type to unsigned cause of "is it a RID" test
hcf_16 			*q;							//source pointer (Tally-part of IFB)
//hcf_16 FAR 		*bq;						//source pointer (Identity or Range records)	;?why bq and not e.g. wq
wci_recordp		p = ltvp->val;				//destination word pointer (in LTV record)
//wci_bufp		cp = (wci_bufp)ltvp->val;	//destination char pointer (in LTV record)

	
	len = ltvp->len;
	type = ltvp->typ;
	
	if ( len > 1 ) {
	
		rc = HCF_SUCCESS;
		switch ( type ) {
			
#if MSF_COMPONENT_ID != COMP_ID_AP1
		  case CFG_TALLIES:																				/* 3 */
			ltvp->len = len = _min( len, (hcf_16)(HCF_TOT_TAL_CNT + HCF_TOT_TAL_CNT + 1) );
			q = (hcf_16*)/*(wci_recordp)*/&ifbp->IFB_NIC_Tallies; //.TxUnicastFrames;
			while ( --len ) *p++ = *q++;
			(void)hcf_action( ifbp, HCF_ACT_TALLIES );
			break;
#endif //COMP_ID_AP1

			

			
			
		  default:
			rc = HCF_ERR_NO_NIC;
			if ( ifbp->IFB_CardStat & CARD_STAT_PRESENT ) {
				rc = HCF_ERR_TIME_OUT;			
				  	if ( type < CFG_RID_CFG_MIN ) {
				  		ltvp->len = 0;
				  	} else {
						(void)cmd_wait( ifbp, HCMD_ACCESS, type );											/* 7 */
						(void)hcfio_string( ifbp, BAP_1, type, 0, (wci_bufp)&i, 1, sizeof(hcf_16), IO_IN );
						ltvp->len = _min( i, len );
						rc = hcfio_string( ifbp, BAP_1, type, sizeof(hcf_16), (wci_bufp)&ltvp->typ, 1, MUL_BY_2(ltvp->len), IO_IN );
						if ( rc == HCF_SUCCESS && i > len ) rc = HCF_ERR_LEN;
					}
			}
		}
	}
	return rc;

}/* hcf_get_info */


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

.MODULE			hcf_initialize  ;?in fact an hcf-support routine, given an hcf_... name just in case we want to
								  export it over the WCI later
.LIBRARY 		HCF
.TYPE 			function
.SYSTEM			msdos
.SYSTEM			unix
.SYSTEM			NW4
.APPLICATION	Card Initialization Group for WaveLAN based drivers and utilities
.DESCRIPTION    ..........., in addition, a light-weight diagnostic test of the NIC
.ARGUMENTS
  int hcf_initialize( IFBP ifbp )

.RETURNS
	HCF_SUCCESS
	HCF_ERR_NO_NIC
	HCF_ERR_TIME_OUT;
	HCF_FAILURE (via cmd_wait)
				(via hcf_get_info)
	HCF_ERR_INCOMP_PRI
	HCF_ERR_INCOMP_STA	
	
  MSF-accessible fields of Result Block:
   	IFB_DUIFRscInd, IFB_NotifyRscInd, IFB_PIFRscInd cleared
   	IFB_MBInfoLen, IFB_RxLen, IFB_RxStat cleared
   	IFB_CardStat  -	CARD_STAT_ENA_0	through CARD_STAT_ENA_6
				  -	CARD_STAT_INCOMP_PRI
				  -	CARD_STAT_INCOMP_STA
   	

.NARRATIVE

  Parameters:
	ifbp		address of the Interface Block

  hcf_initialize will successively:
  -	initialize the NIC by calling ini_hermes
  -	calibrate the S/W protection timer against the Hermes Timer by calling calibrate

  Condition Settings:
	Card Interrupts: Disabled  (Note that the value of IFB_IntOffCnt is unchanged)

  Remarks: since hcf_initialize is the first step in the initialization of the card and since the strategy is to
   detect problems as a side effect of "necessary" actions, hcf_initialize has, in deviation of the general
   strategy, an additional "wait for busy bit drop" at all places where Hermes commands are executed. An
   additional complication is that no calibrated value for the protection count can be assumed since it is
   part of the first execution of hcf_disable to determine this calibrated value (a catch 22). The initial
   value (set at INI_TICK_INI by hcf_connect) of the protection count is considered safe, because:
   o the HCF does not use the pipeline mechanism of Hermes commands.
   o the likelihood of failure (the only time when protection count is relevant) is small.
   o the time will be sufficiently large on a fast machine (busy bit drops on good NIC before counter expires)
   o the time will be sufficiently small on a slow machine (counter expires on bad NIC before the enduser
     switches the power off in despair
	IFB_TickIni is used in cmd_wait to protect the Initialize command. The time needed to wrap a 32 bit counter
	around is longer than many humans want to wait, hence the more or less arbitrary value of 0x10000L is
	chosen, assuming it does not take too long on an XT and is not too short on a scream-machine.
	Once we passed the CARD_STAT_PRESENT test on IFB_CardStat, the other bits can be reset. This is needed
	to have a dynamical adjustment of the Station/Primary Incompatibility flags.
	Especially IFB_TimStat must be cleared (new round, new chances)

 Remarks: First the HCF disables the generation of card interrupts. Next it waits for the Busy bit in the
   Command register to drop (the additional safety required for hcf_initialize as described above). If the Hermes
   passes this superficial health test, the Hermes Initialize command is executed. The Initialize command acts
   as the "best possible" reset under HCF control. A more "severe/reliable" reset is under MSF control via the
   COR register.

 Remarks: If the Initialize of the Hermes succeeds, the S/W protection counter is calibrated if not already
   calibrated. This calibration is "reasonably" accurate because the Hermes is in a quiet state as a result of
   the Initialize command. The hcf_put_info function is used to program the Hermes Tick for its minimum
   interval (1024 microseconds). Programming the Tick interval terminates the old interval timing immediately
   and starts the new interval. Due to this ad-hoc switch the first interval has a larger inaccuracy. By
   timing immediately a second interval the accuracy improves due to the synchronization of HCF and Hermes.
   After this second interval, the Hermes Tick is programmed for its default value of 1 second again.

.NARRATIVE
 2:	Clear all fields of the IFB except those which need to survive hcf_initialize. This is intended to make
 	the behavior and - as a consequence - the debugging of the HCF more reproduceable.

 3:	Disable the interrupt generation facility (see also #30)
 5: Depending on whether there is selective disabling of a single port or a collective disabling of
	all ports a specific bit or all bits representing the enabled ports are reset. In case of "all ports"
	none of the other bits except CARD_STAT_ENABLED is relevant, so as an easy implementation all those
	other bits are cleared.
	The individual bits conveyed in IFB_CardStat are historically grown. To leave the WCI unchanged, the
	individual "port enabled" bits are scattered through IFB_CardStat. As a consequence there is some bit
	arithmetic involved to convert a port number to a bit flag
	The masking of port with HCF_PORT_MASK is a cheap safeguard against I/F violations by the MSF. If the MSF
	supplies an invalid bit pattern, unwanted bits may end up in Hermes Command register via Disable command
	with unpredictable effects.
 7: Check whether CARD_STAT_PRESENT bit of IFB_CardStat is on. If not the remainder of hcf_initialize must be
	skipped to prevent I/O because the I/O space may no longer owned by the HCF, due to a card swap.
12:	When a single port must be disabled AND it is not the only enabled port, that port is selectively