Table 1 HCF and HCF-light System Constants *

1. Executive summary

• Operating System specific aspects. The following OSes are envisaged:

MS-DOS	Netware 4.xx	Windows 3.11
Windows 95	Windows NT	SCO UNIX
MAC OS	Linux 2.0

• Network Operating System specific aspects. The following NOSes are envisaged:

DOS ODI	Netware 4 ODI	NDIS 3
SCO LLI	AppleTalk

• Processor specific aspects. The following processors are envisaged:

Intel 80x86	Motorola 68xxx	PowerPC
AM29K

• Bus specific aspects. The following buses are envisaged:

PCMCIA

PCI

ISA

The Utility Interface Library, or UIL, is a library of functions for WaveLAN/IEEE utilities. The code written on top of the UIL is called Utility Specific Functions, or USF. An UIL-aware MSF must provide functionality for utilities using the UIL (see ref. 5).

The UIL is, just like the HCF, a proprietary library, not available to the Public Domain

To maximize the number of platforms HCF is written in C, rather than in C++.

Since the Hermes shields the HCF of the RF-modem and the remainder of the NIC, the HCF does not need provisions (nor offers them) to interface directly to any component of the NIC other than the Hermes. If in the future requirements to interface to other NIC components are identified, the WCI can be extended.

This document is intended for driver developers. It does not address how to write a driver, it only addresses the facilities offered by the WCI. It is up to the driver developer to determine how these facilities can be used in a particular driver environment. In this respect, the WCI is comparable with the Standard C-library.

1. reference documents

The documents in this section are not available to the General Public. To make this specification useable as stand alone document for HCF-light, parts of ref. 4 are copied into this specification. In case of conflicts between this specification and ref. 4, ref. 4 overrules this specification.

1. WaveLAN/IEEE Documents

 

ref. 1 Top-level Architecture Specification for WaveLAN/IEEE System
Doc. No. TAS 25004 Rev. B

ref. 2 Top-level Architecture Specification for WaveLAN/IEEE Management and Diagnostics
Doc. No. TAS 25050 Rev. A

ref. 3 Top-level Architecture Specification for WaveLAN/IEEE Station Software
Doc. No. TAS 25048 Rev. 5

ref. 4 Hermes Firmware WaveLAN/IEEE Station Functions.
Doc. No. 010245

Ad interim the following design notes are available:
WMDN120 WMAC Controller Software Interface Registers.
WMDN122 WMAC Controller Software Interface Commands.
WMDN148 WMAC Controller Software Interface Frame Structure Formats.
WMDN154 WMAC Controller Software Interface Record Structure Formats.

ref. 5 Interface Specification for Utility Interface Library (UIL).
SDS 25060

ref. 6 Design Specification for WaveLAN-II Deliverables and Migration.
DS 010335

 

2. overview

1. Disclaimer

Text, which is printed in Bold Pitch 14 or marked with a heavy line on the right side, is still under discussion.

Text that is printed in Small Pitch 8 serves as an anchor point for an idea that I want to keep track of in the right context.

 

2. HCF versus HCF-light

This document is maintained as a master version, containing both the HCF and HCF-light information. The information which is not to be publicized for the General Public is placed between markers like ===  begin of HCF only section  == and ==  end of HCF only section  ==. The HCF-light documentation is derived by converting the master version to RTF-format and removing all sections enclosed between those two markers by using an AWK script. This will still leave embedded references to features not supported by HCF-light. A list of acronyms and facilities which are not applicable in HCF-light environments is:

• DUI, DUIF, Utility I/F, UIL, Diagnostic Message
• assert
• Download
• Notify
• Mailbox
• Configuration Table
• Configuration Management, Actor Range, Supplier Range

Note that these acronyms can be embedded in more elaborate entities, e.g. HCF_DUIFRscInd, DUI_STRCT, HCFASSERT. IFB_NotifyRscInd

The conversion of the master version to RTF and post processing with AWK does not have the desired effect in some situations, notably tables. Therefor parts of this documents which are not applicable for HCF-light are not actually removed but labeled as applicable to the HCF only. The hardship posed on the HCF-light user is considered acceptable.

The HCF-light version is provided as is. Lucent Technologies cannot be held responsible for any damage caused by this software

 

1. Network Operating Systems Environment

The HCF supports the IEEE 802.11, IEEE 802.3 and Ethernet_II frame types, HCF-light supports the IEEE 802.3 frame types only

 

 

1. Interfaces

1. Syntax conventions

Parameter sequence:

• If the parameters represent a source and a destination, then the parameter specifying the destination precedes the parameter specifying the source, analogous to the mem-functions of <string.h>
• If the parameters represent a buffer and its length, then the parameter specifying the buffer precedes the parameter specifying the length, analogous to the mem-functions of <string.h>

Parameter type of parameters of a "numerical nature":

• If the parameter or return status is inherently 8, 16, or 32 bits, due to its relationship with the hardware aspects of the NIC, its type is hcf_8, hcf_16, or hcf_32, respectively. Hcf_8, hcf_16, and hcf_32 are unsigned quantities of 8, 16, and 32 bits, respectively. They are defined in the configuration process in HCFCFG.H (see section 4.2.2)
• If the maximum value of a parameter is in the range 0x8000 through 0xFFFF (32786 through 65535), its type is unsigned int.
• If the maximum value of a parameter equals or exceeds 0x10000 (65536), its type is hcf_32.
• If the parameter represents a "command", an enumerated type is used to allow C++ type checking.
• If none of the above applies, the standard type int is used, regardless whether negative values make sense for the parameter.
  By expressing parameters in this "most natural" size for the platform the code must run on, the code generated by the compiler will be optimized (e.g. the use of a 16-bit word in 32-bits mode on an 80x86 results in an override prefix for each machine instruction using that word.)
  By using the signed rather than the unsigned int, it is expected that the chance of introducing bugs as result of unexpected C-promotion rules is the smallest.

It is not expected that hcf_8, hcf_16, hcf_32, or enumerated types are involved in arithmetic expressions or logical expressions other than testing for (un-)equality,

2. Code Adaptation Controls

1. System Constants

System Constants are used to generate code adjusted to environment characteristics, and demands imposed by the hardware environment, and the (Network) Operating System that controls the WaveLAN Software activities.

Most compilers allow System Constants to be defined via the compiler command line, which is an especially appropriate mechanism for HCF_ASSERT. Alternatively, these macros can be defined by the MSF programmer in the HCFCFG.H file.

Note: it is not expected that the HCF-implementation can cope with each and every environment where the WCI can potentially be used. Therefore, a (potential) user can request Lucent Technologies to add specific adaptation for a particular environment. Whether such a request can be honored will be decided by Lucent Technologies. An example of such a niche-adaptation is the BASED macro (ref. 4.2.2)

 

Table 1 HCF and HCF-light System Constants

Constant Symbol	Description	Default1)
HCF_BIG_ENDIAN	Selects Big Endian (a.k.a. Motorola), most significant byte first. Either HCF_BIG_ENDIAN or HCF_LITTLE_ENDIAN must be defined	Undefined
HCF_LITTLE_ENDIAN	Selects Little Endian (a.k.a. Intel), least significant byte first. Either HCF_BIG_ENDIAN or HCF_LITTLE_ENDIAN must be defined	defined
HCF_MAX_MSG	Maximum number of bytes in the message, including MAC header (destination address, source address and length) but excluding FCS and SNAP-header used to encapsulate Ethernet-II frames. HCF_MAX_MSG is used to allocate Tx Frame buffers in NIC RAM and to validate parameters with the HCFASSERT mechanism. The default value is selected as a convenience for the 802.3 environment. Values: 16 – 2318	1514
HCF_MEM_IO	System uses memory mapped I/O. Controls the declaration of hcf_io. Either HCF_PORT_IO or HCF_MEM_IO must be defined	undefined
HCF_PORT_IO	System uses port I/O. Controls the declaration of hcf_io. Either HCF_PORT_IO or HCF_MEM_IO must be defined	defined
HCF_STRICT	Adds additional syntax checking. Primarily intended for the HCF Development Engineers. Can be used by MSF programmers as an additional engineering check on their implementation of IN_PORT_STRING and OUT_PORT_STRING.	undefined
NOTES: 1) The default values are the values specified in the header template file HCFCFG.TPL

Table 1 HCF and HCF-light System Constants

 

3. System Macros and Typedefs

System Macros and typedefs are used to adapt the code to the different brands and versions of compilers to fulfill the needs of the HCF source library. These macros are defined by the MSF programmer in the HCFCFG.H file.

Macro	Description
BASED	Resolves the SS!=DS conflict for the Interrupt Service logic in DOS Drivers
FAR	Resolves the 16 bit segmented versus flat (32-bit) memory model difference.
hcf_8	Defines an 8 bit unsigned quantity.
hcf_16	Defines a 16 bit unsigned quantity.
hcf_32	Defines a 32 bit unsigned quantity.
hcf_io	resolves the size differences between a 64k Port I/O space and a 4G Memory I/O space. Note: this macro is not directly controlled by the MSF-programmer but indirectly via the HCF_PORT_IO or HCF_MEM_IO macros
NOTES: 1) Sample macros are defined in the header template file HCFCFG.TPL

Table 2 HCF and HCF-light System Macros

 

4. Information Transfer

1. I/F Block Concept

Primarily the I/F Block, or IFB, transfers information from the HCF to the MSF. The IFB(s) is/are defined by the MSF. With "defined" is meant the actual location in PC-memory, not the layout. The layout is supplied in HCF.H, one of the include files that are part of the WCI package.

The IFB consists of the following parts:

• a part used by the HCF to pass values to the MSF. The MSF has read only access here.
• a part where all housekeeping of the HCF on a per-NIC basis is done. The MSF has neither read nor write access to this part.

The MSF passes the address of the IFB on all calls to the HCF.

The HCF passes the address of the IFB on all calls to the MSF.

The IFB fields are always "valid", but possibly not "up to date". Certain HCF-functions, e.g. hcf_service_nic (see Appendix 12.14), may update certain fields as a side effect.

 

1. LTV Record Concept

LTV Records are used to exchange data between the MSF and the HCF. An LTV Record consists of three fields.

• a Length field, specifying the combined size of the Type and Data field
• a Type field, identifying how the data in the Data field is to be interpreted
• a Data field, the remainder of the LTV Record, carrying the actual data

1. Hermes Record Concept

Hermes Records are used to exchange Hermes Configuration and Information data between the Hermes and the Host S/W. Hermes Records are LTV records with a value for the Type field in a certain range.

Hermes Records are divided into two groups: Configuration Records and Information Records. Configuration Records are used to influence and adapt the Hermes behavior. Information Records are used to obtain configuration or operational related attributes from the Hermes.

At the NIC, Configuration and Operation data is stored in structures called RIDs, which map one-to-one to Hermes Records. Each type of Configuration or Operation Information has its own unique (numerical) RID. These numbers and the related record layouts are specified in the Hermes specification (ref. 4). The HCF uses mnemonics (as specified by #defines with the prefix CFG_, defined in file MDD.H) to refer to these numerical values. Appendix C - Hermes - HCF Record Correlation, links the WCI mnemonics to a hard coded value and a succinct description. This information is sufficient to correlate the CFG-codes to the Hermes defined RIDs as described in ref. 4.

The WCI transparently offers the MSF access to a subset of those Records.

 

2. Configuration Table concept

The Configuration Table concept is applicable for the HCF only.

 

3. MailBox Concept

The MailBox concept is applicable for the HCF only.

 

4. Download concept

The Download concept is applicable for the HCF only.

 

1. Data Structures

The HCF uses a number of data structures to transfer data between various layers in the architecture. Generally, the HCF does not clear any of these data structures. Only as many bytes as needed or indicated are moved to or from the data structure. The rest of the structure is left unchanged.

Any buffer and data structure used to transfer information across the WCI must have a size of less than 32 Kbytes.

 

1. IFB

Purpose: The IFB is a data structure located in the MSF code, which is used:

• to provide WCI Function execution results to the MSF.
• as working storage for HCF housekeeping on a per NIC basis.
• to identify on HCF-calls made by the MSF, which instance of the WaveLAN NIC must be operated on.
• to identify on MSF-calls made by the HCF, which instance of the WaveLAN NIC is associated with the call.
• to store information related to the MailBox and the Configuration Table.

The IFB is of the type struct IFB_STRCT. File HCF.H declares IFB_STRCT as well as IFBP, a pointer to an IFB_STRCT.

The MSF should only read IFB fields depicted in Appendix E - Data structures.

The MSF should not interpret any other fields of the IFB. If this rule is violated, this may result in serious migration problems.

Writing any field of the IFB negatively affects the integrity of the values as well as HCF code execution !

The MSF should not make any assumptions about the layout of the IFB. Each field must be accessed via its structure member name. No pointer arithmetic to move from one field to another is allowed, to prevent compatibility problems when future releases of the HCF change the IFB layout.

 

1. LTV Records

LTV Records and the specialized form as Hermes Records, are used to exchange information between the NIC and the HCF, NIC and MSF and HCF and MSF . Table 3 shows the general LTV layout, and indicates the Endianess of the fields.

	Size	Description	Endianess
L	16 bits	Length, in words, of the T- and V-fields added together.	Native
T	16 bits	Type, an integer specifying the type of information.	Native
V	N * 16 bits	Value, the "actual" information consisting of one or more sub-fields.	Little Endian, except: when defined differently by the Hermes, e.g. for MAC Addresses. for code CFG_REG_MB where the address of the MailBox is a far pointer in native format. LTV-records for codes related to download, e.g. CFG_DLV_ADDR

Table 3 Layout of LTV-records

Hermes records will be called LTV-records henceforth. The generic LTV record structure is called LTV_STRCT by the HCF, and is defined in file MDD.H. MDD.H contains also a number of specializations of the LTV record structure, e.g. CFG_CNF_PORT_TYPE.

 

1. Configuration Table

The Configuration Table concept is applicable for the HCF only.

 

2. Receive and Transmit Frame Structures

The Receive and Transmit Frame Structures are exchanged between the HCF and the WMAC Controller, and consist of three segments:

• Control fields for the WMAC Controller
• Header information
• Data

For transmit, the control fields are used by the HCF to control how the frame is handled by the WMAC Controller. The MSF-supplied header information and data are used to build the MAC frame for data transfer.

After reception, the control fields are used by the WMAC Controller to inform the HCF/MSF about frame related status information.

The following figure shows the formats of these three segments:

Byte offset		HCF Mnemonic		Transmit Frame Structure			Structure segment	Receive Frame Structure
00	-2E		HFS_STAT		Status		Control	Status
02	-2C				0		Fields
					0		Common for
06	-28		HFS_Q_INFO		SwSupport		802.11	Signal / Silence
							and	Rate
0A	-24				0		802.3
0C	-22		HFS_TX_CNTL		TxControl
0E	-20		HFS_FRAME_CNTL		FrameControl		Header Info	FrameControl
10	-1E		HFS_ID		Duration/ID			Duration/ID
12	00		HFS_ADDR_1		Address1		802.11	Address1
							Format
18	06		HFS_ADDR_2		Address2			Address2
1E	0C		HFS_ADDR_3		Address3			Address3
24	12		HFS_SEQ_CNTL		SequenceControl			SequenceControl
26	14		HFS_ADDR_4		Address4			Address4
2C	1A		HFS_DAT_LEN		DataLen (Little Endian)			DataLen (Little Endian)
2E	00		HFS_ADDR_DEST		DestAddr		Header Info	DestAddr
							802.3
34	06		HFS_ADDR_SRC		SrcAddr		Format	SrcAddr
3A	0C		HFS_LEN		Length (Big Endian)			Length (Big Endian)		(ref Table 4)
3C	0E		HFS_DAT		Data /	SNAP header	Data Info	Data /	SNAP header
3E					Data /	SNAP header		Data /	SNAP header
40					Data /	SNAP header		Data /	SNAP header
42			HFS_TYPE		Data /	E-II Type		Data /	E-II Type	(ref Table 4)
					Data		Common for	Data
							802.11
							and
							802.3
					(Max. 2304 bytes)			(Max. 2304 bytes)

Figure 1 Frame structures formats

The light dashed arrows on the right indicate the 802.3 and 802.3_pure fields.

The heavy dashed arrows on the right indicate the Ethernet-II encapsulated fields.

The light solid arrows on the right indicate the 802.11 fields.

HCF-light only supports the 802.3_pure mode.

These structures are accessed by HCF functions of the Data Transfer Group (see section 5.3).

The gray column of Byte offset values reflect the offset in the Frames as seen on the Host-NIC I/F. These offsets are not useable at the WCI I/F. They are only specified here to ease debugging on the HCF-level.

The non-gray column of Byte offset values reflect the values corresponding with the current implementation of the HCF.

In case of HCF, the offsets specified by the MSF are translated. The hatched HFS_LEN and the gray SNAP header fields are not accessible in case of an encapsulated frame (note that only the HCF has encapsulation support). When the HFS_LEN offset is used in case of an encapsulated frame, the E-II Type rather than the Length is retrieved.

Refer to 4.5 for more information related to Big/Little Endian.

To be protected against future implementation changes, MSF programmers should only use the mnemonics when accessing the Frame structures via the HCF functions of the Data Transfer Group.

Successive hcf_put_data calls will fill sequentially the fields reflected by the arrows in the right border. In case of 802.11, the solid arrow, in case of 802.3, the light dashed arrow and in case of encapsulation, the heavy dashed arrow.

A single hcf_get_data call behaves analogous to hcf_put_data. The important difference is that each hcf_get_data starts at the specified offset. For example specifying 0x0000 in case of 802.11 (or more correctly HFS_ADDR_1), starts at absolute offset 0x0012, specifying 0x0000 or HFS_DAT_LEN in case of 802.3 or encapsulated frames starts at absolute offset 0x002E, specifying HFS_DAT in case of 802.3 or 802.11 frames starts at absolute offset 0x003C, and in case of encapsulated at absolute offset 0x0044.

Note the exceptional handling of the HFS_LEN field.

• In case of 802.3 access of this field yields the length value (absolute offset 0x003A).
• In case of encapsulated Ethernet_II, access yields the type value (absolute offset 0x0042). The length and SNAP-header are not accessible.

 

Offset parameter	rel.offset	Frame type	Abs.offset
HFS_ADDR_1	0x0000	802.11	0x0012
HFS_ADDR_DEST	0x0000	802.3	0x002E
HFS_ADDR_DEST	0x0000	encapsulated	0x002E
HFS_DAT_LEN	0x001A	802.11	0x002C
HFS_DAT_LEN + 2	0x001C	802.11	0x003C
HFS_DAT_LEN	N/A.	802.3	N/A.
HFS_DAT_LEN	N/A.	encapsulated	N/A.
HFS_DAT	0x000E	802.11	0x003C
HFS_DAT	0x000E	802.3	0x003C
HFS_DAT	0x000E	encapsulated	0x0044
HFS_LEN	0x000C	802.3	0x003A
HFS_LEN	0x000C	encapsulated	0x0042
HFS_TYPE (note 1)	N/A.	N/A.	N/A.
HFS_Q_INFO	-0x0028	any Rx Frame	0x0006
Note 1: To access the type field of an encapsulated frame, the mnemonic HFS_DAT must be used. Note 2: For HCF-light only the 802.3 Frame type entries are applicable

Table 4 Correlation frame type, hcf_get_data offset parameter and offsets

2. Data structures and Input/Output Customization

The Input/Output Customization supplies the facilities to adapt the HCF to the I/O specifics of a particular platform, i.e. the low level I/O functions offered by the compiler or (inline) assembler. This issue is additionally complicated by:

• the type of I/O space (port I/O versus memory mapped I/O)
• odd and even byte addressing of NIC RAM
• the Endianess of the platform

Note that throughout this document, the term word is used interchangeably with hcf_16 and must be interpreted as a 16-bits quantity.

The type of I/O space is reflected by the System Constants HCF_PORT_IO and HCF_MEM_IO.

The Host – NIC I/F to handle bytes has some intricacies. The HCF split the byte oriented input and output as requested via hcf_put_data, hcf_get_data, hcf_put_info and hcf_get_info, in appropriate sequences of byte and word based input/output streams. This transformation is done because the word oriented I/O is much faster. Therefore, the types of parameters used in IN_PORT_STRING and OUT_PORT_STRING are not the most natural at first glance.

The NIC has a Little Endian (LE) architecture.

The Host may be either Big Endian (BE) or Little Endian as reflected by the System Constants HCF_LITTLE_ENDIAN and HCF_BIG_ENDIAN.

The term Native Endian (NE) is used to denote the Endianess of the Host.

The consequences of the Endianess for LTVs are specified in 4.5.2. The LTV-related conversions from Big to Little Endian and vice versa are handled by the HCF.

Messages are assumed to be in the correct Endianess for the 802.3 protocol so no conversion is needed.

 

1. Transmit/Receive Frames

These frames are defined by the Hermes. Therefore, they are LE, with one exception to accommodate easy implementation of the 802.3 protocol. This exception is the Length field embedded in the 802.3 frame starting at offset 0x2E (see Figure 1 Frame structures formats).

 

2. LTV-records

At the WCI-level, the Endianess of LTV-records is defined as:

• the L- and T-field have "native" Endianess as seen from the Host
• the V-field is Little Endian

As a consequence:

• the HCF as well as the MSF can manipulate L and T in a natural way, e.g. use L as a loopcounter, do range checking on T values.
• when passing the L- and T-field from NIC and the Host or vice versa, the HCF must adjust the Endianess, which is automatically done when using the IN_/OUT_PORT_WORD macros
• when passing the V-field to/from the Host, the HCF is not sensitive for the Endianess, which is automatically done when using the IN_/OUT_PORT_STRING macros
• when creating/interpreting the V-field, an BE MSF must be aware of the deviating Endianess.

 

1. IN_PORT_WORD(port)

IN_PORT_WORD is a macro supplied by the MSF-programmer in HCFCFG.H to read a word (16 bits) from the specified port.

Depending on the Endianess of the Host, IN_PORT_WORD passes the words with or without byte swapping from the NIC to the Host. This makes IN_PORT_WORD suitable for:

• the Length and Type field of all Configuration Records
• the complete set of Control fields of the Receive Frame Structure, i.e. all control fields preceding the Header Info parts and the control fields embedded in the 802.11 Header Info part. Note that the Length field in the 802.3 Header Info part is not considered a control field

For internal purposes, the HCF uses IN_PORT_WORD to access

• the Value part of a some Configuration Records, e.g. cnfOwnATIMWindow (FC05)
• the Value part of Information Frame Structure, e.g. Communication Tallies (F100)

However when these structures are requested by the MSF as a result of hcf_get_info, they still adhere to the main rule of L- and T fields are NE and V-fields are LE.

 

1. OUT_PORT_WORD(port, value)

OUT_PORT_WORD is a macro supplied by the MSF-programmer in HCFCFG.H to write a word (16 bits) to the specified port

Depending on the Endianess of the Host, OUT_PORT_WORD passes the words with or without byte swapping from the NIC to the Host.

 

2. Void IN_PORT_STRING( port, dest, len)

IN_PORT_STRING is a macro supplied by the MSF-programmer in HCFCFG.H to read len number of words from the specified port to the (FAR) address dest in Host-RAM.

Note that len specifies the number of words, NOT the number of bytes.

• although len specifies the number of words, dest MUST be a char pointer

Regardless of Endianess of the Host, IN_PORT_STRING passes the words without byte swapping from the NIC to the Host. This makes IN_PORT_STRING suitable for:

• the Address sub-fields of 802.11 Header of the Receive Frame Structure
• the complete 802.3 Header of the Receive Frame Structure
• the DataInfo part of the Receive Frame Structure

 

1. void OUT_PORT_STRING( port, src, len)

OUT_PORT_WORD is a macro supplied by the MSF-programmer in HCFCFG.H to write len number of words from the (FAR) address src in PC-RAM to the specified port

Note that len specifies the number of words, NOT the number of bytes.

• although len specifies the number of words, src MUST be a char pointer

Regardless of Endianess of the Host, OUT_PORT_STRING passes the words without byte swapping from the NIC to the Host.

 

1. common notes for IN_PORT_STRING and OUT_PORT_STRING

The peculiar combination of word-length and char pointers for IN_PORT_STRING as well as OUT_PORT_STRING is justified by the assumption that it offers a more optimal algorithm

For convenience of the MSF-programmer, both IN_PORT_STRING and OUT_PORT_STRING are allowed to modify their parameters (although some might argue that this would constitute bad coding practice). This has its implications on the HCF, e.g. these macros are never called with parameters that have side effects, e.g. auto-increment.

• In the Microsoft implementation of inline assembly, it is O.K. to corrupt all flags except the direction flag and to corrupt all registers except the segment registers and EDI, ESI, ESP and EBP (or their 16 bits equivalents).

Other environments may have other constraints

• In the Intel environment it is O.K to have a word (as a 16 bits quantity) at a byte boundary, hence IN_/OUT_PORT_STRING can move words between PC-memory and NIC-memory with as only constraint that the words are on a word boundary in NIC-memory. This does not hold true for all conceivable environments, e.g. an Motorola 68xxx does not allow this, in other words whenever there is a move from address in 2*n in one memory type to address 2*m+1 in the other type, the current templates for IN_/OUT_PORT_STRING are unsuitable. Current assumption is that the boundary conditions imposed by these type of platforms prevent this case from materializing. This assumption is asserted when HCF_ALIGN is set at 2 (ref Table 1 HCF and HCF-light System Constants )

By selecting (or writing) the appropriate Macro definitions by means of modifying the "#if defined <macro-name>" or "#if 0/1" lines in file HCFCFG.H (see Appendix A.2 - Template Files), the HCF can be adjusted for the I/O characteristics of a specific compiler and run-time environment.

If needed the macros can be modified or replaced with definitions appropriate for a specific platform. Should any changes be made, it is appreciated if the reader informs Lucent Technologies WCND Utrecht. That way the changes can become part of the next release of the WCI.

The "prototypes" and functional description of the macros are:

Prototype	Description
hcf_8 IN_PORT_BYTE( hcf_io port )	Reads a byte (8 bits) from the specified port.
hcf_16 IN_PORT_WORD( hcf_io port )	Reads a Little Endian word (16 bits) from the specified port and converts it to Native Endian format.
void OUT_PORT_BYTE( hcf_io port, hcf_8 value )	Writes a byte (8 bits) to the specified port.
void OUT_PORT_WORD( hcf_io port, hcf_16 value)	Writes a Little Endian word (16 bits) to the specified port after converting it from Native Endian format.
void IN_PORT_STRING( hcf_io port, hcf_8 FAR *dest, int len )	Reads len number of words from the specified port to the (FAR) byte address dest in PC-RAM without conversion of the Endianess. Note that len specifies the number of words, NOT the number of bytes.
void OUT_PORT_STRING( hcf_io port, hcf_8 FAR *src, int len )	Writes len number of words from the (FAR) byte address src in PC-RAM to the specified port without conversion of the Endianess. Note that len specifies the number of words, NOT the number of bytes.

Table 5 Macros for optimization of string I/O

2. functional descriptions

This chapter presents a general descriptions of the WCI functions which for this purpose are divided into a number of functional groups. For each group, an overview is given of the functions in the group and a general description and possible special considerations to be taken into account when using the functions.

The primary focus is to make the explanations useful as reference material. Therefore, concepts are sometimes used before they are properly introduced and a second read of this manual may be needed for the novice.

 

1. Connection Group

The Connection related functions control the storage of the housekeeping information of the HCF, and the "handle" used by the MSF and HCF to identify to one another.

Connect Function

To execute WCI Functions, the HCF needs an IFB to indicate a NIC. This IFB is initialized by the Connect Function. The Connect Function does not access the NIC itself. The Disconnect Function releases the IFB. Between the Connect and the Disconnect Function, the HCF may autonomously and a-synchronously access the IFB, in read as well as in write mode.

Disconnect Function

Every call of the Connect Function must eventually be followed by a call of the Disconnect Function. Calls to the Connect Function can not be nested.

The MSF may only call the other HCF-functions after successful execution of the Connect function and before the Disconnect Function.

 

2. NIC Configuration Group

The NIC Configuration related functions maintain and control the run-time behavior of a physical NIC.

The NIC is set into operational mode by the Enable Function. The latter can be (temporarily ) reversed by the Disable Function. Although the Enable and Disable Function are antonyms, there is no restriction on their sequencing, in other words, they may both be called multiple times in arbitrary sequence without being paired or balanced. Each time one of these functions is called, the effects of the preceding calls cease. Even in non-operational mode (i.e. initially and after the Disable function is called for all ports which have been enabled), I/O may still occur, especially as result of one of the following functions:

• Enable function
• Download (see the Configuration functions)
• Diagnose (see the Action functions)

Enable Function

The Enable Function is used by the MSF to enable data transmission and reception on a particular port. HCF-light and stations only support port #0. An AccessPoint can support so called WDS links at port #1 through #6.

The Enable Function initializes the NIC hardware settings for data transmission and reception for a particular port in accordance with the current configuration . The Enable Function reports failures when they are detected as side effect of actions that must be performed anyhow.

Default the HCF runs in a polled mode. By means of the Action function, the NIC interrupt generation can be enabled, in which case the NIC generates interrupts when transmit, receive and info event related incidents occur after the execution of the Enable Function.

• Note that hcf_enable by itself only enables data transmission and reception, it does not enable the Interrupt Generation mechanism (ref 6.8.1 for more details).

 

Disable Function

The Disable Function is used by the MSF code to bring a particular port in an inactive state as far as data transmission and reception are concerned. In case of multiple ports, the NIC is changed into an inactive state - leaving the hardware in such a state that interrupts are no longer generated - when the last enabled port is disabled. The Disable Function reports failures when they are detected as side effect of actions that must be performed anyhow.

.

Action Function

The Action Function can be used by the MSF to change NIC Modes (see section 6.8) and to start a number of actions in the NIC.

The Action Function supports a number of action-code pairs that are antonyms. Except for the interrupt en-/disabling, none of these actions have to be balanced. Each time one of these action codes is used, the effects of the preceding use cease. In addition, the Action Function provides a number of codes to start actions in the NIC.

Configuration Functions

The Configuration Functions are primarily intended for driver MSFs to change and retrieve the (non-binary) NIC Configuration settings in volatile memory, and to retrieve operational information (e.g. Tallies). In addition, they can make changes to NIC Configuration settings in non-volatile memory and download firmware to volatile as well as non-volatile NIC memory. The Configuration functions are also used to exchange information between the MSF and the HCF, i.e. setup of the Mailbox, reading from the Mailbox.

 

1. Data Transfer Group

The execution of the Data Transfer functions is driven either by a polling strategy in the MSF or by the NIC interrupt handling provisions of the MSF.

One mode of using the WMAC is transferring 802.3 frames across the 802.11 channel. Design of the WMAC is such that this mode is easy and straightforward for the Host S/W to use. The WCI is also geared to make this mode simple for the MSF.

"Message" as used in the context of the Data Transfer functions, does not only include the part of an 802.3 or 802.11 MAC frame that follows the DataLen field of the DataInfo substructure of the Receive/Transmit Frame Structure (see section 4.4.4), but also Addressing, control information (802.11 only), 2 byte DataLen field, however the 4 bytes Frame Check Sequence (CRC-32) and the physical frame envelope are not part of the message. The HCF is transparent for the actual message contents (i.e., the values are not validated) with the exception of Ethernet-II en-/ decapsulation in a SNAP frame.

Service NIC Function

The Service NIC Function supports the NIC event service handling process. It performs the appropriate actions to service the NIC, such that the event cause is eliminated and related information is saved. The Service NIC Function is executed by the MSF ISR or polling routine as first step to determine the event cause(s).

The Service NIC Function may have side effects related to the Mailbox (see section 4.3.5) and Resource Indicators (see Put Data and Send Diagnostic Message Function).

Get Data Function

The Get Data Function must be executed by the MSF to obtain data and/or Control Fields or Header Info fields of the message that is reported to be available by the Service NIC Function.

The Get Data Function copies all or a part of the message data available in the Card memory into a buffer structure provided by the MSF. Only data of the message indicated by the Service NIC Function is obtained. Repeated execution of the Get Data Function, without Service NIC execution in between, results in acquisition of data of the same message. Execution of the Service NIC function may result in the availability of a new message, but it certainly makes the message reported by the preceding Service NIC function, unavailable.

Put Data Function

The Put Data Function places the 802.3 header or the 802.11 addressing, control and length information, and the message contents on the card for message transmission.

The MSF must check availability of resources. The Resource Indicator (IFB_PIFRSCInd) must be non-zero before executing the first call to the Put Data Function. If resources are available, the Resource Indicator is set to zero on the first call to the Put Data Function by the HCF, and the MSF no longer has to check its value in subsequent Put Data Function calls for the same frame to be sent. If resources are not available, the MSF should wait until they become available (via the Service NIC Function) before calling the Put Data Function.

Send Function

The Send Function activates transmission. The Send Function must be preceded by one or more Put Data Function calls.

Put Header Function

The Put Header Function is applicable for the HCF only.

Resend Function

The Resend Function is applicable for the HCF only.

Send Diagnostic Message Function

The Send Diagnostic Message Function is applicable for the HCF only.

 

2. MSF Support Routines

The MSF Support Routines are applicable for the HCF only.

 

 

1. Implementation Notes

This chapter presents a number of isolated topics needed to give the reader a background to use the WCI in a specific environment.

 

1. AccessPoint/Station functionality

If HCF_AP is defined, the following ADDITIONAL functionality is available:

• Download volatile NIC memory
• CFG_NOTIFY type code support in hcf_put_info function
• Depositing of NIC Tallies into the MailBox

If HCF_AP is defined, the following functionality is not available:

• check compatibility with Station functionality supplied by the Hermes
• accumulated NIC Tallies in IFB

If HCF_STA is defined, the following ADDITIONAL functionality is available:

• Download non-volatile NIC memory

If HCF_STA is defined, the following functionality is not available:

• N/A.

 

1. Alignment restrictions

Some platforms can access words on odd boundaries (with possibly a performance impact). On other platforms, such an access results in a memory access violation. It is assumed that at all places where the HCF casts a char pointer into a word pointer, the alignment criteria are met. This puts some restrictions on the MSF, which are assumed to be "automatically" fulfilled at the applicable platforms.

The system constant HCF_ALIGN (see Table 1) can be used to specify the alignment restriction. The default value is 0, meaning no alignment. A value of 2 means word alignment. Other values are invalid. If the alignment restriction is not met and HCF_ASSERT is defined, the HCF will generate an assert.

2. Polled control

The HCF defaults to interrupts off. Polled control consists of calling function hcf_service_nic at a suitable rate. If after this call field IFB_RxLen indicates data reception, then the MSF must process the data, and loop back.

(See also section 6.10 for more information about the actions that must be taken when the NIC needs servicing.)

 

3. Interference control

A number of WCI functions may not be interrupted by other HCF-activities. Therefore, the execution of these functions must be protected in some way from this interference. The functions concerned are the following:

• hcf_put_data
• hcf_send
• hcf_get_info
• hcf_put_info
• hcf_send_diag_msg (not available in HCF-light),

It is assumed that the MSF handles the problem of one MSF thread being pre-empted by another MSF thread. Pre-emption of an MSF thread as result of a NIC interrupt can be prevented by calling hcf_action with code HCF_ACT_INT_OFF before and with code HCF_ACT_INT_ON after. To allow MSF procedure nesting, the hcf_action calls with HCF_ACT_INT_OFF/_ON may be nested.

An alternative way is to disable the processor interrupts, e.g. at an 80x86 platforms with CLI and STI instructions.

If a number of the above calls are executed in sequence, the whole sequence may be protected by a single disable/enable interrupts pair.

In (most) polled environments, interference will not occur.

 

• Note that in multithreaded systems the HCF_ACT_INT_ON/_OFF mechanism may not be sufficient to prevent re-entrancy problems.

• Note that a sequence of hcf_put_data and hcf_send called from task level to transmit msg_1 must not be interrupted by a sequence of hcf_put_data and hcf_send called from interrupt service level to transmit msg_2. This statement is made to make the picture of how the HCF works more clear to the reader. The IFB_PIFRscInd mechanism already prevents this scenario from happening in a well-designed MSF.

 

1. Connect/Disconnect control

The HCF_ASSERT logic is sensitive to the sequencing of hcf_connect and the installation of the ISR: interrupt-based MSFs must install interrupt service routing (ISR) code at the vector related to the IRQ number of the WaveLAN NIC after calling function hcf_connect but before any HCF Function is executed. Details of the ISR are treated in section 6.10.

 

2. Transmission control

Transmission control is based on the command resource indicators, which are located in the IFB. For example, one of these command resource indicators reflects whether the Hermes command resource is available to handle message transmissions. The resource indicators are maintained by the HCF and should only be interpreted but not changed by the MSF. More details are given in section 5.3. There are two sources for messages to be transmitted. These sources are:

• the protocol stack (the "normal" source for drivers)
• the Driver/Utility I/F (ref. 5) (not available in HCF-light)

To make these two sources independent, each has its own resource indicator, called IFB_PIFRscInd and IFB_DUIFRscInd, respectively.

When the IFB_PIFRscInd is not available, the MSF must handle the queuing of the Transmit frame and check the resource indicator periodically after a hcf_service_nic.

When the IFB_DUIFRscInd is not available, a possible strategy is that the MSF reports the inability to transmit to the utility, which retries the transmission after a delay.

 

1. NIC Configuration

Actual NIC behavior, as controlled by the WCI Functions, is influenced by alterable NIC Configuration parameters. The values of these parameters can be changed by calls to hcf_put_info (see 12.9). The parameters are specified in Appendix D: Configuration parameters.

 

2. NIC Modes

Actual NIC behavior, as controlled by the WCI Functions, is in addition to the NIC Configuration, influenced by a number of alterable NIC Modes. A NIC Mode can be considered as a binary NIC Configuration.

All NIC Modes are directly controlled by hcf_action (see 12.1). Modes are also affected by the following WCI Functions:

· Connect Function (see 12.1).

 

1. NIC Interrupts (Enabled/Disabled)

If NIC interrupts are Enabled, interrupt events are signaled through the hardware interface. Otherwise, those events are not signaled.

The NIC Interrupts Enabled/Disabled Mode is only one link in the chain of interrupt handling components. E.g. in a PC environment, the PCIC, the PIC and the IF-flag in the processor control register play a role too. The NIC Interrupts Enabled/Disabled Mode allows or disallows the generation of interrupts by the NIC. For the sake of simplicity, this specification will use the phrases enabling and disabling interrupts where it is clear from the context what is meant.

The disabling and enabling of interrupts are antonyms. These actions must be balanced. For each "disable interrupts" there must be a matching "enable interrupts". The disable interrupts may be executed multiple times in a row without intervening enable interrupts, in other words, the disable interrupts may be nested. The interrupt generation mechanism is disabled at the first call with HCF_ACT_INT_OFF. The interrupt generation mechanism is re-enabled when the number of calls with HCF_ACT_INT_ON matches the number of calls with INT_OFF.

The HCF defaults to NIC interrupts disabled after hcf_connect. To enable interrupts function hcf_action must be called with code HCF_ACT_INT_ON. This call may be executed before or after calling hcf_enable.

• Note for transmit/receive related interrupts to become active, both hcf_action( HCF_ACT_INT_ON ) and hcf_enable must have been executed, but their sequence is arbitrarily. As a side effect, this results in interrupts being inactive after an hcf_action( HCF_ACT_DIAG ) until hcf_enable. The latter is supposed to be part of the unblock process ( ref 6.17 ). Note that there exist other interrupts sources (e.g. info events ) which may occur after the interrupts are enabled, regardless whether hcf_enable() is called.

• Note that the NIC Interrupts Enabled/Disabled Mode play an important role to prevent re-entrancy problems (ref 6.4).

 

1. Card presence (In/Out)

The HCF does not monitor card presence. It is up to the MSF to notify the HCF of changes in NIC presence.

The HCF defaults to NIC absent (=Out). When the HCF considers the NIC as absent, a hcf-function call does not result in any I/O. When the MSF notifies HCF of NIC presence, the NIC is initialized. If the NIC is already "logically" enabled, the NIC is "physically" enabled again. With "logically" enabled is meant that there has been an arbitrary sequence of hcf_enable and hcf_disable calls and the last of that sequence was hcf_enable. It is not relevant whether the card was present or absent during these calls, however as stated before, if the card is absent, no I/O occurs. With "physically" enabled is meant that the HCF actual executes the I/O to perform the appropriate Hermes commands.

• Note that a notification of NIC presence results in a NIC initialization regardless whether the NIC was present or absent according to the internal housekeeping of the HCF.

• Note that a notification of NIC absence / presence plays a role during the COR Reset and PCIC H/W Reset (ref 6.12).

 

1. Timer tick interrupts (On/Off)

This mode is applicable for the HCF only.

 

2. Frame type (802.11/802.3/802.3 pure)

This mode is applicable for the HCF only.

 

1. Card Swap

This feature is applicable for the HCF only.

 

2. ISR

For background information, refer to chapter 6.4.

A possible ISR structure (for an 80x86 platform) is:

• disable interrupt generation by NIC, e.g.
• call hcf_action( ifbp, HCF_ACT_INT_OFF )
• optionally enable processor interrupt
  or
• do neither of above (assuming interrupts are disabled at entry in the ISR)
• service PIC
• call hcf_service_nic
• one or more calls to hcf_get_data to pass the data of the received message from NIC RAM to protocol stack
• the sequence of hcf_service_nic followed by one or more calls to hcf_get_data may be repeated if more than one message was received
• if a message to transmit is pending and if a resource is available, call hcf_put_data (once or more) and hcf_send
• re-enable interrupt generation by NIC by appropriate counter-actions for strategy used at entry of ISR, e.g.
• disable processor interrupt
• call hcf_action( ifbp, HCF_ACT_INT_ON )
  or
• do neither of above

If the HCF_ACT_INT_ON/OFF strategy is used, all the intermediate actions may be handled as is appropriate for the OS-environment, e.g. deferred procedure calls at "task"-level in Windows NT.

If the HCF_ACT_INT_ON/OFF strategy is used, the processor interrupts must be disabled before the HCF_ACT_INT_ON action, to prevent that an interrupt which may have been raised by the NIC in the meantime, will result in re-entering the ISR before the stack is clean. If this would occur a sufficiently large number of time, the stack would overrun.

If the strategy to let processor interrupts be disabled is selected, the ISR must be programmed efficiently to keep the processor monopolization "reasonable". This strategy also is easily jeopardized by calling on OS or protocol support routines that enable the processor interrupts.

 

1. C / C++

Despite the fact that the HCF is implemented in C, the macro EXTERN_C is used in HCF.H to prevent name mangling when a C++ compiler is used. The macro EXTERN_C is defined in HCFCFG.H. This provision is offered because several of the conveniences of the Microsoft Visual C Integrated Development Environment do not function in a C environment. This is seen as a shortcoming in the Microsoft product, and the EXTERN_C macro is implemented to get around this deficiency and still be able to have a mixed Assembler and C environment.

 

2. Reset

COR Reset and PCIC H/W Reset are controlled by the MSF. The HCF is in principal unaware of a COR Reset. Therefore the MSF must precede the COR Reset with a call to hcf_action with HCF_ACT_CARD_OUT as parameter. To get back into operational mode the COR Reset must be followed with a call to hcf_action with HCF_ACT_CARD_IN as parameter.

 

3. Memory use

In most environments, there is only a single IFB per driver that could be made globally accessible.

From the viewpoint of a (classic) driver developer, the indirect pointer based access mechanism to the IFB, may seem a waste at first glance.

However in a research project, removing IFB as parameter from all procedures (both the ones defined by the WCI as well as the internal procedures) and replacing all IFB-access with direct access, saved only 3% on memory size of the object generated by the HCF. The size of the MSF will reduce the relative size overhead even further.

 

4. Notify Control

This feature is applicable for the HCF only.

 

5. Download

This feature is applicable for the HCF only.

 

6. msf_assert

This feature is applicable for the HCF only.

 

7. Blocking

This feature is applicable for the HCF only.

 

8. MSF_COMPONENT_…. and DUI_COMPAT_……

This feature is applicable for the HCF only.

 

9. Exclusions

Applicable for the HCF only.

 

10. User scenarios

Refer to DN

 

11. Pitfalls

• I/O space claimed too late
  In some OS-environments a driver must request an I/O space (base + size) before it may perform I/O. This request must be granted before any hcf-function except hcf_connect is invoked. Earlier versions of the HCF did not always access the NIC at calls like hcf_put_info(), hence earlier HCF implementation may successfully run when this constraint is violated, while newer version may fail
• I/O space claimed too small
  The current version of the NIC uses an I/O space of 0x40 bytes. Claiming too small a size by the OS may result in a successful initialization but breakdown later
• Incorrect customization of the I/O macros
  Most samples contained in HCFCFG.H are based on compilers which have Output support routines which specify the destination with the first parameter and the value with the second parameter. The most noteworthy exception is the Linux/GCC section, which uses the AT&T convention of specifying the value with the first parameter and the destination with the second parameter.
• Wrong network configuration selection
  The network configuration is selected by means of CFG_CNF_PORT_TYPE. The NIC defaults to a type of 3, Pseudo IBSS or Ad Hoc mode. The most common setup however seems to be a type of 1, IEEE 802.11 Infrastructure or Basic Service Set. This implies that most MSFs must explicitly use hcf_put_info() to set type at 1.
• Ethernet-II encapsulation
  IEEE 802.11 and 802.3_pure (and as a consequence, HCF-light) have no provisions to handle the type field of Ethernet-II (a.k.a. DIX Ethernet) frames. To get around this problem, this type of frames must be encapsulated in 802.3 formatted frames. Two encapsulation schemes are in common use ( Tunnel encapsulation and RFC 1042 Encapsulation). The HCF handles the encapsulation automatically, however the HCF-light variety does not do encapsulation. Note that encapsulation enlarges the frame size which must be taken into account when defining HCF_MAX_SIZE.
• Resource checking
  The MSF must check the resource indicators (IFB_PIFRscInd, IFB_DUIFRscInd and IFB_NotifyRscInd) before executing functions which require these resources

 

1. APPENDIX A - HCF SOURCE CODE LIBRARY

The Hardware Control Functions ( HCF ) Source Code Library contains the following file categories:

Information Files: Plain text files containing information for MSF programmers using the HCF Source Code Library files.

Template Files: C-source files containing the default set-up for specific HCF header files.

Code Generation Files: C-source files to be compiled to produce the HCF object files for linkage with the MSF code.

 

 

1. Appendix A.1 - Information Files

The information files contents need to be known by the MSF developer for proper usage of the HCF.

Those files are maintained in combination with the C-source files, and are therefore inherently more up-to-date than the Design Specification. Examination of those files is needed to reveal deviations from this specification caused by HCF code improvements and enhancements for broader applicability.

The following table lists the information files:

File Name	Description
HCF_CHNG.TXT	Contains interface and implementation change history information relevant for MSF developers. This includes directions to migrate an MSF from using a preceding version of HCF to the next version.
HCF_IF.TXT	Contains interface definition information. This includes descriptions of implementation related Code Adaptation Controls, and WCI Functions interface descriptions derived from the C-source files.

Table 6 Information Files

3. Appendix A.2 - Template Files

Before usage of the HCF Source Code Library to generate object code for linkage to a new MSF, all files with a .TPL extension should be copied to files with the same root file name but with a .H extension. The resulting header files should be reviewed and changed to adapt the HCF code properly for that specific MSF, as well as to the development environment used for code generation.

If another HCF version is used, existing .H files used for a specific MSF should be verified against the contents of the .TPL files that are part of the other version.

The following table lists the template files:

File Name

Description

HCFCFG.TPL

Functional behavior related System Constants (refer to Table 1 HCF and HCF-light System Constants). Development environment related I/O macros to define code parts of associated routines in HCFIO.C Development environment related macro EXTERN_C (refer to 6.11 ) Development environment related macro HCFASSERT Development environment related macro to define pointers to structures used in information exchange between HCF and MSF

Table 7 Template Files

 

2. Appendix A.3 - Code Generation Files

Before code generation is performed, first all header files should be prepared ( see preceding Template Files section ).

Before the MSF object code is generated, a statement to include the HCF.H file should be available in the MSF source code. This takes care of inclusion of other files needed to generate the code for external connections to the HCF code.

The .C files need to be compiled to produce the HCF object code to be linked to the MSF object code.

The following table lists the code generation files:

File Name	Description
MDD.H	This file contains information needed for both MSF and USF programmer HCF error codes UIL error codes various enumerations for HCF and UIL CFG-codes for LTV-records definition of various structures: LTV_STRCT several specific LTV_STRCTs DUI_STRCT
HCF.H	WCI Functions and MSF Support Routines prototypes, and variables, structures, and constants definitions.
HCF.INC	HCF.H contents converted for usage by ASM MSF modules (MASM 6.11 compatible, other assemblers may require modifications)
HCFDEF.H	Structures, macros, and constants definitions specific for HCF.C and HCFIO.C
HCF.C	WCI Functions and related coding.
HCFIO.C	All I/O functions to perform actual NIC access. Supplying these functions in a separate file allows easy optimization for a specific H/W platform

Table 8 Code Generation File

1. Appendix B - HCF defined LTV-Records

HCF-light does not define any LTV-records additional to the Hermes.

 

2. Appendix C - Hermes - HCF Record Correlation

This section lists the correlation between HCF mnemonics for Configuration Information Records Identifiers (RIDs) and the Hermes hexadecimal values. The Hermes specification (see ref. 4) distinguishes Configuration RIDs and Information RIDs.

"Appendix B - HCF defined " lists the HCF defined Info Types.

The mnemonics are defined in file HCF.H.

The mnemonics are prefixed with CFG_, however to condense the layout of the tables, the CFG_ prefix is left out.

When an entry in the columns AP/STA and PRI/STA contains AP, PRI or STA, the entry is applicable only for AccessPoint, Primary or Station Firmware. The behavior when invoked while not applicable is not defined.

 

1. Configuration RIDs

The following sets of Configuration RIDs have been assigned:

• Network Parameters, Static Configuration Entities
• Network Parameters, Dynamic Configuration Entities
• Behavior Parameters

 

Network Parameters, Static Configuration Entities
RID hex	Parameter Name excluding CFG_prefix	AP/ STA	Description
FC00	CNF_PORT_TYPE	STA	Connection control characteristics.
FC01	CNF_OWN_MAC_ADDR	STA	MAC Address of this node.
FC02	CNF_DESIRED_SSID	STA	Service Set identification for connection.
FC03	CNF_OWN_CHANNEL		Communication channel for BSS creation.
FC04	CNF_OWN_SSID	STA	IBSS creation Identification
		AP	ESS Service Set Identification
FC05	CNF_OWN_ATIM_WINDOW	STA	ATIM Window time for IBSS creation.
FC06	CNF_SYSTEM_SCALE		System Scale that specifies the AP density
FC07	CNF_MAX_DATA_LEN		Maximum length of MAC Frame Body data.
FC08	CNF_WDS_ADDR	STA	MAC Address of corresponding WDS Link node.
FC09	CNF_PM_ENABLED	STA	Switch for ESS Power Management (PM) On/Off.
FC0A	CNF_PM_EPS	STA	Switch for ESS PM EPS/PS Mode.
FC0B	CNF_MCAST_RX	STA	Switch for ESS PM Multicast reception On/Off.
FC0C	CNF_MAX_SLEEP_DURATION	STA	Maximum sleep time for ESS PM.
FC0D	CNF_HOLDOVER_DURATION	STA	Holdover time for ESS PM.
FC0E	CNF_OWN_NAME		Identification text for diagnostic purposes.
FC10	CNF_OWN_DTIM_PERIOD	AP	Beacon intervals between successive DTIMs.
FC11	CNF_WDS_ADDR1	AP	Port 1 MAC Adrs of corresponding WDS Link node.
FC12	CNF_WDS_ADDR2	AP	Port 2 MAC Adrs of corresponding WDS Link node.
FC13	CNF_WDS_ADDR3	AP	Port 3 MAC Adrs of corresponding WDS Link node.
FC14	CNF_WDS_ADDR4	AP	Port 4 MAC Adrs of corresponding WDS Link node.
FC15	CNF_WDS_ADDR5	AP	Port 5 MAC Adrs of corresponding WDS Link node.
FC16	CNF_WDS_ADDR6	AP	Port 6 MAC Adrs of corresponding WDS Link node.
FC17	CNF_MCAST_PM_BUF	AP	Switch for PM buffering of Multicast Messages.

Table 9 Network Parameters, Static Configuration Entities

Network Parameters, Dynamic Configuration Entities
RID hex	Parameter Name excluding CFG_prefix	AP/ STA	Description
FC80	GROUP_ADDR	STA	Multicast MAC Addresses for message reception.
FC81	CREATE_IBSS	STA	Switch for IBSS creation On/Off.
FC82	FRAGMENTATION_THRH	STA	Fragment length unicast message transmission.
FC83	RTS_THRH	STA	Frame length for RTS/CTS handshake control.
FC84	TX_RATE_CONTROL	STA	Data rate control for message transmission.
FC85	PROMISCUOUS_MODE	STA	Switch for Promiscuous mode reception On/Off.
FC90	FRAGMENTATION_THRH0	AP	Port 0 fragment length unicast msg transmission.
FC91	FRAGMENTATION_THRH1	AP	Port 1 fragment length unicast msg transmission.
FC92	FRAGMENTATION_THRH2	AP	Port 2 fragment length unicast msg transmission.
FC93	FRAGMENTATION_THRH3	AP	Port 3 fragment length unicast msg transmission.
FC94	FRAGMENTATION_THRH4	AP	Port 4 fragment length unicast msg transmission.
FC85	FRAGMENTATION_THRH5	AP	Port 5 fragment length unicast msg transmission.
FC96	FRAGMENTATION_THRH6	AP	Port 6 fragment length unicast msg transmission.
FC97	RTS_THRH0	AP	Port 0 frame length RTS/CTS handshake control.
FC98	RTS_THRH1	AP	Port 1 frame length RTS/CTS handshake control.
FC99	RTS_THRH2	AP	Port 2 frame length RTS/CTS handshake control.
FC9A	RTS_THRH3	AP	Port 3 frame length RTS/CTS handshake control.
FC9B	RTS_THRH4	AP	Port 4 frame length RTS/CTS handshake control.
FC9C	RTS_THRH5	AP	Port 5 frame length RTS/CTS handshake control.
FC9D	RTS_THRH6	AP	Port 6 frame length RTS/CTS handshake control.
FC9E	TX_RATE_CONTROL0	AP	Port 0 data rate control for message transmission.
FC9F	TX_RATE_ CONTROL 1	AP	Port 1 data rate control for message transmission.
FCA0	TX_RATE_ CONTROL 2	AP	Port 2 data rate control for message transmission.
FCA1	TX_RATE_ CONTROL 3	AP	Port 3 data rate control for message transmission.
FCA2	TX_RATE_ CONTROL 4	AP	Port 4 data rate control for message transmission.
FCA3	TX_RATE_ CONTROL 5	AP	Port 5 data rate control for message transmission.
FCA4	TX_RATE_ CONTROL 6	AP	Port 6 data rate control for message transmission.

Table 10 Network Parameters, Dynamic Configuration Entities

This feature is applicable for the HCF only.

Table 11 Behavior Parameters

 

1. Information RIDs

The following sets of Information RIDs have been assigned:

• NIC Information
• MAC Information
• Modem Information

 

NIC Information
RID hex	Parameter Name excluding CFG_prefix	PRI/STA	Description
FD02	PRI_IDENTITY	PRI	Primary Functions firmware identification.
FD03	PRI_SUP_RANGE	PRI	Primary Functions I/F; Supplier compatibility
FD04	CFI_ACT_RANGES_PRI	PRI	Controller I/F; Actor compatibility
FD0A	NIC_SERIAL_NUMBER	PRI	Network Interface Card serial number.
FD0B	NIC_IDENTITY	PRI	Network Interface Card identification
FD0C	MFI_SUP_RANGE	PRI	Modem Interface; Supplier compatibility
FD0D	CFI_SUP_RANGE	PRI	Controller I/F; Supplier compatibility
FD10	CHANNEL_LIST		Allowed communication channels.
FD11	REG_DOMAINS		List of intended regulatory domains.
FD12	TEMP_TYPE		Hardware temperature range code.
FD13	CIS		PC Card Standard Card Information Structure
FD20	STA_IDENTITY	STA	Station Functions firmware identification
FD21	STA_SUP_RANGE	STA	Station Functions I/F; Supplier compatibility
FD22	MFI_ACT_RANGES_STA	STA	Modem I/F; Actor compatibility
FD23	CFI_ACT_RANGES_STA	STA	Controller I/F; Actor compatibility

Table 12 NIC Information

 

MAC Information
RID hex	Parameter Name excluding CFG_prefix	AP/ STA	Description
FD40	PORT_STAT	STA	Actual MAC Port connection control status.
FD41	CURRENT_SSID	STA	Identification of the actually connected SS.
FD42	CURRENT_BSSID		Identification of the actually connected BSS.
FD43	COMMS_QUALITY	STA	Quality of the Basic Service Set connection.
FD44	CURRENT_TX_RATE	STA	Actual transmit data rate.
FD45	OWN_BEACON_INTERVAL		Beacon transmit interval time for BSS creation.
FD46	CUR_SCALE_THRHS		Actual System Scale thresholds settings.
FD47	PROTOCOL_RSP_TIME		Max. time to await a response to a request msg.
FD48	SHORT_RETRY_LIMIT		Max. umber of transmit attempts for short frames.
FD49	LONG_RETRY_LIMIT		Max. umber of transmit attempts for long frames.
FD4A	MAX_TX_LIFETIME		Maximum transmit frame handling duration.
FD4B	MAX_RX_LIFETIME		Maximum received frame handling duration.
FD4C	CF_POLLABLE	STA	Contention Free pollable capability indication.
FD4D	AUTHENTICATION_ALGORITHMS		Available Authentication Algorithms indication.
FD4E	AUTHENTICATION_TYPE		Available Authentication Types indication.
FD4F	PRIVACY_OPTION_IMPLEMENTED		WEP Option availability indication.
FD80	CURRENT_TX_RATE1	AP	Actual Port 1 transmit data rate.
FD81	CURRENT_TX_RATE2	AP	Actual Port 2 transmit data rate.
FD82	CURRENT_TX_RATE3	AP	Actual Port 3 transmit data rate.
FD83	CURRENT_TX_RATE4	AP	Actual Port 4 transmit data rate.
FD84	CURRENT_TX_RATE5	AP	Actual Port 5 transmit data rate.
FD85	CURRENT_TX_RATE6	AP	Actual Port 6 transmit data rate.
FD86	OWN_MACADDRESS	AP	Unique local node MAC Address.
FD87	PCF_INFO	AP	Point Coordination Function capability information.

Table 13 MAC Information

 

 

 

Modem Information
RID hex	Parameter Name excluding CFG_prefix		Description
FDC0	PHY_TYPE		Physical layer type indication.
FDC1	CURRENT_CHANNEL		Actual frequency channel used for transmission.
FDC2	CURRENT_POWER_STATE		Actual power consumption status.
FDC3	CCAMODE		Clear channel assessment mode indication.
FDC4	CCATIME		Clear channel assessment time.
FDC5	MAC_PROCESSING_DELAY		MAC processing delay time.
FDC6	SUPPORTED_DATA_RATES		Data rates capability information.

Table 14 Modem Information

1. Appendix D: Configuration parameters

To define Data field formats, the following format descriptors are used:

Descriptor	Meaning
Word	16-bit area used as a Bit area, 2 Bytes, a Boolean, or an Integer. For serial data transfer the least-significant bit (bit 0) is transmitted first and the most-significant one (bit 15) last. The least-significant Byte is located at the lower memory address.
Byte	8-bit area that contains an unsigned value. Value range: 0.. 255 (00..FF hexadecimal).
Bit Area	Word with a specific meaning for each separate bit or smaller group of bits.
Boolean	Word that contains a value of either 0000 or 0001 hexadecimal, which indicates one of the following context dependent meanings: 0000 = False, No, Off, or Disabled 0001 = True, Yes, On, or Enabled.
Integer	Word that contains an unsigned value. Value range: 0..65535 (0000..FFFF hexadecimal).
Byte Area	1 or more consecutive Words. Each word contains 2 Bytes. Storage sequence: Byte 1 in the least-significant byte of the Word at the lowest memory address, Byte 2 in the most-significant byte of that word, Byte 3 in the least-significant byte of the Word at the next higher memory address, etc.
Byte String	2 or more consecutive Words. The first Word is an Integer and the remainder is a Byte Area. The Integer contains the StringLen value, which indicates the number of significant bytes (0 or more) that are consecutively stored in the Byte Area, starting with the least-significant Byte of the Word that follows the Integer. If the Integer value is odd, the last Byte is located in the least-significant byte of the Word in which it is stored.
Integer Area	2 or more consecutive Words. Each word contains an Integer. Storage sequence: Integer 1 is in the Word at the lowest memory address, Integer 2 is in the Word at the next higher memory address, etc.

 

1. Network Parameters, Static Configuration Entities

Changing any of the parameters in this section will only take effect after the execution of a call to hcf_enable (see Appendix 12.5).

 

1. cnfPortType

Word Offset	Field name	Size (words)
0	RecordLen: 2	1
1	RID: FC00	1
2	cnfPortType	1

Field descriptions:

Name:	CnfPortType
Description:	Defines the connection control characteristics: 1 = Basic Service Set (BSS) 2 = Wireless Distribution System (WDS) 3 = Pseudo IBSS
Format:	Integer
Values:	Range: 1..3; Default: 3

 

2. cnfOwnMACAddress

Word Offset	Field name	Size (words)
0	RecordLen: 4	1
1	RID: FC01	1
2	cnfOwnMACAddress	3

Field descriptions:

Name:	cnfOwnMACAddress
Description:	Defines the MAC Address that identifies this station for data transfer.
Format:	Byte Area
Values:	The first byte of this address must be X2, X6, XA, or XE (X being any hex value) indicating an Individual address.

Till the MAC Address is modified by means of hcf_put_info, the MAC Address defaults to the burnt-in MAC Address of the NIC.

 

3. cnfDesiredSSID

Word Offset	Field name	Size (words)
0	RecordLen: 18	1
1	RID: FC02	1
2	cnfDesiredSSID	17

Field descriptions:

Name:	CnfDesiredSSID
Description:	Identifies the Service Set the station is to connect to. A zero length string indicates ‘any’ SSID.
Format:	Byte String
Values:	Range: StringLen: 0..32; Default: StringLen = 0

 

 

4. cnfOwnChannel

Word Offset	Field name	Size (words)
0	RecordLen: 2	1
1	RID: FC03	1
2	cnfOwnChannel	1

Field descriptions:

Name:	CnfOwnChannel
Description:	Indicates the CHNL_ID number of the communication frequency channel to be used for creating an BSS. If the provided value is 0 or the communication channel is not allowed (see ChannelList Information record) the related OwnChannel value remains unchanged during Enable command execution.
Format:	Integer
Values:	Range: 0..14; Default: PDR 0105 - Default channel number (3)

 

5. cnfOwnSSID

Word Offset	Field name	Size (words)
0	RecordLen: 18	1
1	RID: FC04	1
2	cnfOwnSSID	17

Field descriptions:

Name:	CnfOwnSSID (a.k.a. Independent_Network_Name )
Description:	Independent_Network_Name specifies the network (Service Set) the station is to create as an IBSS, or the ESS the AP is part of
Format:	Byte String
Values:	Range: StringLen: 1..32; Default: StringLen = 21 and Bytes = "non-specified SSID !!"

 

6. cnfOwnATIMWindow

To be added after stabilization of the firmware implementation

 

7. cnfSystemScale

Word Offset	Field name	Size (words)
0	RecordLen: 2	1
1	RID: FC06	1
2	CnfSystemScale	1

Field descriptions:

Name:	CnfSystemScale (a.k.a. AP_Density)
Description:	Specifies the Access Points density in the ESS: 1 = Low density 2 = Medium density 3 = High density
Format:	Integer
Values:	Range: 1..3; Default: 1

AP_Density controls the density of the Access Points in the ESS. This influences the Modem Threshold settings (EnergyDetectThreshold, DeferThreshold, and CarrierDetectThreshold), and in a station also the Roaming Threshold settings (CellSearchThreshold, and OutOfRangeThreshold).

 

8. cnfMaxDataLength

Word Offset	Field name	Size (words)
0	RecordLen: 2	1
1	RID: FC07	1
2	cnfMaxDataLength	1

Field descriptions:

Name:	cnfMaxDataLength
Description:	Defines the maximum number of Data bytes that can be stored in Transmit and Receive Frame Structures (as reflected in the DataLen field of these structures, see Frame Structures Format chapter).
Format:	Integer
Values:	Range: 350..2304; Default: [STA] 2304 and [AP] 1500 Note that the default value does not accommodate Ethernet-II encapsulation for maximum frame size

 

 

9. cnfWDSAddress

This feature is applicable for the HCF only.

 

 

10. cnfPMEnabled

To be added after stabilization of the firmware implementation

 

11. cnfPMEPS

To be added after stabilization of the firmware implementation

 

 

12. cnfMulticastReceive

To be added after stabilization of the firmware implementation

Receive_All_Multicasts specifies whether the station must receive all multicast frames (with addresses specified by the protocol stack) when using Power Management. When this is the case, the station will have to wake up frequently to receive the multicast frames. This causes less optimal power savings.

 

 

13. cnfMaxSleepDuration

Word Offset	Field name	Size (words)
0	RecordLen: 2	1
1	RID: FC0C	1
2	CnfMaxSleepDuration	1

To be added after stabilization of the firmware implementation

 

14. cnfPMHoldoverDuration

To be added after stabilization of the firmware implementation

 

15. cnfOwnName

Word Offset	Field name	Size (words)
0	RecordLen: 18	1
1	RID: FC0E	1
2	CnfOwnName	17

Field descriptions:

Name:	CnfOwnName (a.k.a. Station_Name)
Description:	Identifies the printable-text name that is associated with the network node. Printable means that the text (i.e., the significant bytes of the Byte String) consists only of ASCII code vales from the following character ranges: a..z, A..Z, 0..9, and characters: " ‘ ( ) , - . / : = ? space.
Format:	Byte String
Values:	Range: StringLen: 0..32; Default: StringLen = 0

Station_Name is used for diagnostic purposes as a user-friendly identification of stations. If possible, this should be the system's name that is already used for other (networking) purposes, like the Host name for TCP/IP, or the sysName for SNMP Management.

 

16. cnfOwnDTIMPeriod

Word Offset	Field name	Size (words)
0	RecordLen: 2	1
1	RID: FC10	1
2	cnfOwnDTIMPeriod	1

Field descriptions:

Name:	cnfOwnDTIMPeriod
Description:	Specifies the number of Beacon intervals between successive Delivery Traffic Identification Maps (DTIMs).
Format:	Integer
Values:	Range: 1..65535; Default: 1

 

17. CnfWDSAddress1..6

This feature is applicable for the HCF only.

 

18. CnfMulticastPMBuffering

To be added after stabilization of the firmware implementation

Word Offset	Field name	Size (words)
0	RecordLen: 2	1
1	RID: FC17	1
2	cnfMulticastPMBuffering	1

Field descriptions:

Name:	cnfMulticastPMBuffering
Description:	Controls if multicast MAC Frames are buffered for transmission after DTIM. If Off, multicast MAC Frames are directly placed in the output queue.
Format:	Boolean
Values:	Default: No

 

3. Network Parameters, Dynamic Configuration Entities

Changing the value of any of the parameters in this section will directly influence the operation of the NIC, i.e. no call to hcf_enable is needed.

 

1. GroupAddresses

Word Offset	Field name	Size (words)
0	RecordLen: n*3+1; n = 0..16; Default: 1 (i.e., n = 0)	1
1	RID: FC80	1
2	MacAddress 1 (optional)	3
		3
		3
n*3-1	MacAddress n (optional)	3

Field descriptions:

Name:	MACAddress
Description:	Each of the 0 to 16 MAC Addresses specifies a multicast address that is checked as part of the received message acceptance procedure. Notice that only address values with the Group Address bit On will have effect. Other address values are neglected.
Format:	Byte Area

 

 

2. CreateIBSS

Word Offset	Field name	Size (words)
0	RecordLen: 2	1
1	RID: FC81	1
2	CreateIBSS	1

Field descriptions:

Name:	CreateIBSS
Description:	Controls if IBSS creation is enabled. If Disabled, no IBSS creation is performed by this station.
Format:	Boolean
Values:	Default: No

 

 

4. FragmentationThreshold

Word Offset	Field name	Size (words)
0	RecordLen: 2	1
1	RID: FC82	1
2	FragmentationThreshold	1

Field descriptions:

Name:	FragmentationThreshold
Description:	Defines the number of bytes used for the fragmentation boundary for directed messages.
Format:	Integer
Values:	Range: 256..2346; even numbers only ! ; Default: 2346

 

 

5. RTSThreshold

Word Offset	Field name	Size (words)
0	RecordLen: 2	1
1	RID: FC83	1
2	RTSThreshold	1

Field descriptions:

Name:	RTSThreshold
Description:	Defines the number of bytes used for the RTS/CTS handshake boundary.
Format:	Integer
Values:	Range: 0..2347; Default: 2347

 

 

6. TxRateControl

Word Offset	Field name	Size (words)
0	RecordLen: 2	1
1	RID: FC84	1
2	TxRateControl	1

Field descriptions:

Name:	TxRateControl
Description:	Defines the data rate(s) for message transmission: 1 = Fixed 1 Mbit 2 = Fixed 2 Mbit 3 = Auto Fallback
Format:	Integer
Values:	Range: 1..3; Default: 3

 

7. PromiscuousMode

Word Offset	Field name	Size (words)
0	RecordLen: 2	1
1	RID: FC85	1
2	PromiscuousMode	1

Field descriptions:

Name:	PromiscuousMode
Description:	Controls if Promiscuous mode reception is enabled. If Disabled, only messages destined for this Station are accepted.
Format:	Boolean
Values:	Default: No

 

 

2. Appendix E - Data structures

The table below shows the MSF accessible fields of the IFB. Writing any field negatively affects the integrity of the values as well as HCF code execution! The MSF should not make any assumptions about the layout of the IFB. Each field must be accessed via its structure member name. No pointer arithmetic to move from one field to another is allowed to prevent compatibility problems when future releases of the HCF change the IFB layout.

Table 15 MSF readable parts of the IFB

Type	Member Name	Description
hcf_16	IFB_CardStat	Bit-field representing the status of the card indicating whether a NIC is present, and enabled. 0x8000: Internal HCF-flag MSF defined card as being present. Controlled via hcf_action(HCF_ACT_CARD_IN/_OUT). When NIC is absent (reflected by bit 0x8000 = 0), no I/O is done, "side-"effects of hcf_put_config functions are not influenced. bit 0x4000: Internal HCF-flag MSF defined one or more ports as being enabled (see hcf_enable(HCF_PORT_<n>) ). bit 0x2000 (CARD_STAT_INCOMP_PRI) Controlled by hcf_disable (note that hcf_enable call hcf_disable) HCF actor range for Primary Firmware has no overlap with range supplied by Primary Firmware (see ref. 6). bit 0x1000 (CARD_STAT_INCOMP_STA) Controlled by hcf_disable (note that hcf_enable call hcf_disable) HCF actor range for Station Firmware has no overlap with range supplied by Station Firmware (see ref. 6) bit 0x0800: Internal HCF-flag NIC is initialized bit 003F: Internal HCF-flags, indicating stages in command processing
hcf_8	IFB_DUIFRscInd	Value indicating the command resource availability for the Driver-Utility I/F (i.e. hcf_send_diag_msg). Values: No command resource Ü 0 Command resource available Ü 01h-FFh
hcf_32	IFB_HCF_Tallies [HCF_HCF_TAL_CNT]	A set of tallies maintained by the HCF NoBufInq No buffer available reported by Inquiry command NoBufInfo No buffer available for unsolicited Notify frame NoBufMB No space available in MailBox MiscErr Miscellaneous errors time out on BAP Initialization time out on Tx Frame Allocation time out on AUX port En-/Disabling time out on completion synchronous part Hermes Command synchronously completed Hermes Command doesn't match original command Request to put zero-length MailBox Info block EngCnt; Engineering Count Data Corruption Workaround caught
hcf_8	IFB_HCFVersionMajor	Major version of the HCF. 0x01 for this release
hcf_8	IFB_HCFVersionMinor	Minor version of the HCF. Incremented for each coding maintenance cycle. 0x01 for the Initial release
hcf_io	IFB_IOBase	I/O address of Hermes chip as passed by MSF at hcf_connect call
hcf_16	IFB_IORange	I/O Range used by Hermes chip
hcf_16	IFB_MBInfoLen	Value of the Length-field of the oldest LTV-record in the MailBox (0 if MailBox empty or no MailBox registered). This value can be used to determine whether there is any message in the MailBox without having to make a call to hcf_get_info.
hcf_32	IFB_NIC_Tallies [HCF_NIC_TAL_CNT]	A set of tallies maintained by the Hermes (ref. 4) TxUnicastFrames; TxMulticastFrames; TxFragments; TxUnicastOctets; TxMulticastOctets; TxDeferredTransmissions; TxSingleRetryFrames; TxMultipleRetryFrames; TxRetryLimitExceeded; TxDiscards; RxUnicastFrames; RxMulticastFrames; RxFragments; RxUnicastOctets; RxMulticastOctets; RxFCSErrors; RxDiscards_NoBuffer; TxDiscardsWrongSA; RxWEPUndecryptable; RxMsgInMsgFragments; RxMsgInBadMsgFragments;
hcf_8	IFB_NotifyRscInd	Value indicating the command resource availability for the Notify command. Values: No command resource Ü 0 Command resource available Ü 01h-FFh
hcf_8	IFB_PIFRscInd	Value indicating the command resource availability for the Protocol Stack (i.e. hcf_put_data and hcf_send). Values: No command resource Ü 0 Command resource available Ü 01h-FFh
hcf_8	IFB_RxLen	Number of received bytes in 802.3 view (Including DestAddr, SrcAddr, MACLength, excluding sum check) of active Rx Frame Values: No Rx Data available Ü 0000h Rx Data Available Ü 1 - HCF_MAX_MSG
hcf_8	IFB_RxStat	Status field of active Rx Frame (ref. 4) 0xE000 Message type 0x0700 MAC Port 0x0003 Error Status 0x0001 FCS error 0x0002 Undecryptable
hcf_8	IFB_Version	version of the IFB. Incremented for each layout change of the IFB. Intended for Engineering Utilities which interpret the IFB for debugging purposes. 0x00 for the Initial release
Grayed text is only supplied to ease debugging. No MSF code should depend on it If a field contains grayed bits, the MSF implementation should take in account that these bits can have any value and the MSF should not depend on the value of these bits.

Table 15 MSF readable parts of the IFB

1. Appendix F - Function descriptions

Check on descriptions related to RscInd and CardStat since these areas are significantly changed due to a change in hcf_disable/enable/initialize strategy

1. ACTION FUNCTION ( hcf_action )

Purpose: Changes the run-time NIC behavior controlled by the binary NIC Configuration settings.

Syntax: int hcf_action( IFBP ifbp,
hcf_action_cmd cmd );

Returns: HCF_SUCCESS
HCF_FAILURE (;?cmd_wait)
HCF_ERR_TIME_OUT (;?cmd_wait)
HCF_INT_PENDING (HCF_ACT_INT_OFF only)
nesting level of HCF_ACT_INT_OFF (HCF_ACT_INT_ON only)

Note that HCF_ERR_NO_NIC is not a return status of hcf_action. Except for HCF_ACT_DIAG, all actions can either be performed regardless the absence or presence of the NIC, or the actions are directly related to informing the HCF of absence or presence( HCF_ACT_CARD_OUT/_IN). In case of HCF_ACT_DIAG while no NIC is present, this is reflected in the CFG_DIAG LTV carrying the result.

Parameters:

Entry
ifbp	Value indicating the address of the IFB Values: Address Þ Any value
action	Enumerated value indicating the Action to be performed. Values: Disable NIC Interrupts Þ HCF_ACT_INT_OFF Enable NIC Interrupts Þ HCF_ACT_INT_ON MSF Reported Card insertion Þ HCF_ACT_CARD_IN MSF Reported Card removal Þ HCF_ACT_CARD_OUT Hermes Inquire Tallies command Þ HCF_ACT_TALLIES ================ HCF only section (start) ================ Hermes Inquire Scan command Þ HCF_ACT_SCAN Hermes Diagnose command Þ HCF_ACT_DIAG Enable timer tick interrupts Þ HCF_ACT_TICK_ON Disable timer tick interrupts Þ HCF_ACT_TICK_OFF activate Assert reporting Þ HCF_ACT_ASSERT_ON de-activate Assert reporting Þ HCF_ACT_ASSERT_OFF Activate 802.11 frame mode Þ HCF_ACT_802_11 Activate 802.3 frame mode Þ HCF_ACT_802_3 Activate 802.3 frame mode without Ethernet-II encapsulation Þ HCF_ACT_802_3_PURE ================ HCF only section (end) =================
Interrupts	In case of HCF_ACT_INT_OFF: NIC interrupts don’t care

Exit
Return Value	In case of HCF_ACT_INT_OFF: no interrupt pending Ü HCF_SUCCESS interrupt pending Ü HCF_INT_PENDING
	In case of HCF_ACT_INT_ON: Number of unbalanced HCF_ACT_INT_OFF calls (zero is balanced) intended for debugging purposes only
	In case of HCF_ACT_TALLIES and HCF_ACT_SCAN: Action completed successfully Ü HCF_SUCCESS Action timed out Ü HCF_ERR_TIME_OUT Unspecified error Ü HCF_FAILURE
	================ HCF only section (start) ================ In case of HCF_ACT_DIAG: action completed successfully Ü HCF_SUCCESS action timed out Ü HCF_ERR_TIME_OUT unspecified error Ü HCF_FAILURE ================ HCF only section (end) ================
	In all other cases Ü HCF_SUCCESS
Ifb	Fields affected in case of HCF_ACT_CARD_IN · IFB_CardStat CARD_STAT_INCOMP_PRI set if Primary Firmware incompatible CARD_STAT_INCOMP_STA set if Station Firmware incompatible CARD_STAT_ENABLED set if one or more ports are logically enabled
Interrupts	In case of HCF_ACT_INT_OFF: NIC Interrupts Disabled
	In case of HCF_ACT_INT_ON: NIC Interrupts Disabled or Enabled depending on the number of preceding HCF_ACT_INT_OFF commands
	In all other cases: NIC Interrupts unchanged (see also 6.8.1)

Description:

The command HCF_ACT_DIAG is only operational if the NIC is present.

The commands HCF_ACT_TALLIES and HCF_ACT_SCAN are only operational if the NIC is enabled (which implies that the NIC is present).

The commands HCF_ACT_INT_OFF/_ON, HCF_ACT_TICK_OFF/_ON and HCF_ACT_802_11/_3/_3_PURE are operational regardless of NIC presence, but in case of NIC absence, the commands will take effect when the NIC is re-inserted.

The NIC Mode is controlled as follows by the Actions:

Disable NIC Interrupts

Sets NIC Interrupts mode Disabled. For more details on the relationship between Disabling and Enabling NIC Interrupts and Disabling and Enabling Data communication the reader is referred to 6.8.1.

Enable NIC Interrupts

Sets NIC Interrupts mode Enabled.

MSF reported card insertion

The MSF informs the HCF of a card insertion. The NIC is restored to its operational mode. This restoration includes restoring the NIC configuration as set by means of hcf_put_config, under the assumption that the Configuration Table has a sufficient size. The Data Communication is enabled or disabled depending on the history of hcf_disable and hcf_enable calls. The Interrupt generation is enabled or disabled depending on the history of hcf_action calls with HCF_ACT_IN_OFF and HCF_ACT_INT_ON.

MSF reported card removal

The MSF informs the HCF of a card removal. The internal housekeeping of the HCF is updated such that none of the hcf-functions with the exception of hcf_action with HCF_ACT_CARD_IN as parameter will result in I/O. Note that actions like hcf_put_config may still have an effect, but that effect will only materialize at NIC insertion.

Hermes Inquire Tallies command

The Hermes Inquire Tallies command requests the Hermes to provide its current set of tallies. If successful, the Hermes resets its tallies after delivering them to the HCF. The new tallies are stored in the IFB. The MSF has the choice to either call hcf_action with code HCF_ACT_TALLIES and read the tallies wanted directly from the IFB, or to call hcf_get_info with code CFG_TALLIES. In the latter case the tallies will be stored in the LTV-record passed as a parameter (the HCF tallies are updated too). As a USF does not have direct access to the IFB, the USF-programmer does not have this choice, therefore, HCF_ACT_TALLIES is not exported to the UIL-interface.

Enable / Disable NIC interrupts

INT_OFF and INT_ON calls may be nested, but must be balanced. First an INT_OFF call has to be made. The interrupt generation mechanism is disabled at this first call with INT_OFF. There may be more INT_OFF calls than INT_ON calls. It is not allowed, however, to have more INT_ON calls than INT_OFF calls. The interrupt generation mechanism is re-enabled when the number of calls with INT_ON matches the number off calls with INT_OFF.

The following commands are supported by the HCF only.

• Hermes Inquire Scan command
• Hermes Diagnose command
• Enable timer tick interrupts
• Disable timer tick interrupts
• Activate 802.3 frame mode
• Activate 802.3 pure frame mode
• Activate 802.11 frame mode

Hermes Inquire Scan command

The Hermes Inquire Scan command starts a scan sequence on the Hermes. The HCF puts the result of this action in the MailBox (for a USF to read).

Hermes Diagnose command

The Hermes Diagnose command starts a diagnose sequence on the Hermes. The HCF puts the result of this action in the MailBox (for a USF to read).

Enable timer tick interrupts

Enables timer tick interrupt generation by the NIC.

Disable timer tick interrupts

Disables timer tick interrupt generation by the NIC.

Activate 802.3 frame mode

Informs the HCF that 802.3 frames will be offered for transmission. The HCF en/decapsulates Ethernet-II frames

Activate 802.3 pure frame mode

Informs the HCF that 802.3 frames will be offered for transmission. The HCF does not en/decapsulates Ethernet-II frames

Activate 802.11 frame mode

Informs the HCF that 802.11 frames will be offered for transmission. The HCF does not en/decapsulates Ethernet-II frames

The easiest safe strategy to set the 802.3/11 frame mode is when the NIC is disabled.

 

Assert fails if

• ifbp is zero or other recognizable out-of-range value.
• an invalid action code is specified in parameter cmd.
• the card is busy with a download, or a diagnose command.
• HCF_ACT_INT_ON commands outnumber the HCF_ACT_INT_OFF commands since last hcf_enable.

2. CONNECT FUNCTION ( hcf_connect )

Purpose: Initializes the HCF housekeeping part of the IFB. Grants access right for the HCF to the IFB.

Syntax: void hcf_connect( IFBP ifbp,
hcf_io io_base );

Returns: N/A

Parameters:

Entry
ifbp	(Near) pointer indicating the address of the IFB Values: Address Þ Any value
io_base	Value indicating the I/O Base address of the NIC Values: I/O Base Address Þ Non-zero multiple of 0x40
Interrupts	In case of HCF_ACT_INT_OFF: NIC interrupts don’t care

Exit
ifb	Fields affected: All MSF accessible fields, which are not specified below, are zero-filled · IFB_IOBase Ü parameter io_base · IFB_HCFVersionMajor Ü Major version of the HCF 0x01 for the Initial release · IFB_HCFVersionMinor Ü Minor version of the HCF. Incremented for each coding maintenance cycle. 0x01 for the Initial release · IFB_IORange Ü 0x40 · IFB_Version Ü version of the IFB layout
Interrupts	Not applicable

Description:

hcf_connect passes the MSF-defined location of the IFB to the HCF. This address must be used as a handle with all subsequent HCF-function calls and the HCF uses the address of the IFB as a handle when it performs a call(back) of an MSF-function.

hcf_connect initializes the IFB, its own house-keeping area, as well as the fields which may be accessed by the MSF. All MSF accessible fields which are not explicitly mentioned in the Exit description above, are zero filled.

hcf_connect makes the HCF default to card absence, interrupts disabled, and 802.3 frames (see Appendix 12.1). It is the responsibility of the MSF programmer to adjust these settings when necessary.

IFB_HCFVersionMajor and IFB_HCFVersionMinor (both of type hcf_8) store the major and minor version of the HCF, respectively, in a kind of BCD format. The four high-order bits of each of these two fields store the first decimal position of the version number in binary form, the four low-order bits store the second decimal position.

hcf_connect does not interact with the NIC at all. This implies that:

• the NIC Interrupt Enabled/Disabled state is not initialized by hcf_connect
• the NIC need not be present when hcf_connect is called

It is the responsibility of the MSF to:

• assure the correctness of the I/O Base address.

Assert fails if

• hcf_connect is called more than once without intervening hcf_disconnect.
  This Assert is not fail safe. There is a small chance that it fails while it shouldn’t.
• ifbp is zero
• ifbp is not properly aligned ( ref HCF_ALIGN in Table 1).
• I/O Base Address is zero.
• I/O Base Address is not a multiple of 0x40.

 

2. DISABLE FUNCTION ( hcf_disable )

Purpose: Disables data transmission and reception.

Syntax: int hcf_disable( IFBP ifbp,
hcf_16 port );

Returns: HCF_SUCCESS
HCF_ERR_NO_NIC
HCF_ERR_INCOMP_PRI
HCF_ERR_INCOMP_STA
HCF_ERR_TIME_OUT
HCF_ERR_LEN
HCF_FAILURE

Parameters:

Entry
ifbp	Value indicating the address of the IFB Values: Address Þ Any value
port	Number indicating the MAC Port MAC Port Values: · MAC Port 0 Þ HCF_PORT_0 ================ HCF only section (start) ================ · MAC Port 1 Þ HCF_PORT_1 · MAC Port 2 Þ HCF_PORT_2 · MAC Port 3 Þ HCF_PORT_3 · MAC Port 4 Þ HCF_PORT_4 · MAC Port 5 Þ HCF_PORT_5 · MAC Port 6 Þ HCF_PORT_6 ================ HCF only section (end) ================

Exit
Return value	Number indicating the function execution result Values: Success Ü HCF_SUCCESS No card present in slot Ü HCF_ERR_NO_NIC Primary functions firmware not compatible Ü HCF_ERR_INCOMP_PRI Station functions firmware not compatible Ü HCF_ERR_INCOMP_STA Timer calibration failed Ü HCF_ERR_TIME_OUT Error in retrieving compatibility information from card Ü HCF_ERR_LEN Hermes failure or HCF bug Ü HCF_FAILURE
Ifb	Fields affected: · IFB_DUIFRscInd Ü 0000h · IFB_NotifyRscInd Ü 0000h · IFB_PIFRscInd Ü 0000h · IFB_MBInfoLen Ü 0000h · IFB_RxLen Ü 0000h · IFB_RxStat Ü 0000h · IFB_CardStat CARD_STAT_ENABLED cleared if no enabled ports are left
Interrupts	NIC interrupts disabled.

Description:

The hcf_disable command is likely to change when the MAC Port mechanism is implemented

The presence and status of the NIC is tested. If a NIC is present hcf_disable guarantees to bring the card in a disabled state.

hcf_disable does not influence IFB_IntOffCnt. A call to hcf_enable following hcf_disable will only enable the card if IFB_IntOffCnt is equal to zero.

If the NIC is not present or not enabled, the HCF housekeeping is updated accordingly.

If the NIC is present and enabled

• NIC interrupts are disabled
• the NIC is reset by means of a Cold Initialize command to the Hermes
• In the very first call to hcf_disable, the HCF timer mechanism will be calibrated. To make this calibration as accurate as possible, it may help to disable all interrupts prior to this first call of hcf_disable. Note that if hcf_disable is called while the NIC is not present, hcf_disable will be called automatically when the MSF calls hcf_action( HCF_ACT_CARD_IN ) when the NIC is inserted.

When the Disable function is called all Receive frames and all pending Transmit frames on the NIC are discarded.

 

IFB_CardStat is a bit pattern. Bit CARD_STAT_INCOMP_PRI is set if the HCF is not compatible with the Primary Firmware on the NIC, bit CARD_STAT_INCOMP_STA is set if the HCF is not compatible with the Station Firmware on the NIC (ref. 6). The other bits of IFB_CardStat should not be interpreted by the MSF but are available for debugging purposes.

 

Assert fails if

• ifbp is zero or other recognizable out-of-range value.
• hcf_disable is called without a prior call to hcf_connect.
• port is out of range
• timer calibration failed.
• card is busy with a download or a diagnose command.

 

2. DISCONNECT FUNCTION ( hcf_disconnect )

Purpose: Disables data transfer and releases the IFB. Revokes access right from the HCF to the IFB.

Syntax: void hcf_disconnect( IFBP ifbp );

Returns: N/A

Parameters:

Entry
ifbp	Value indicating the address of the IFB Values: Address Þ Any value

Exit
ifb	Fields affected: All fields are zero-filled
Interrupts	NIC interrupts disabled.

Description:

All data transfers and all NIC interrupts for the NIC related with the IFB, are disabled.

The IFB is released, meaning that the HCF will no longer access, in read nor write mode, the IFB

Every call of hcf_connect must (eventually) be followed by a call of hcf_disconnect. After a disconnect the MSF should first call function hcf_connect before any other WCI function. After a call to hcf_disconnect the MSF must de-install the ISR if it was installed before (see section 6.10).

Assert fails if

• ifbp is zero or an other recognizable out-of-range value is encountered.
• hcf_disconnect is called without a prior call to hcf_connect.
• the card is busy with a download or a diagnose command.

 

2. ENABLE FUNCTION (hcf_enable )

Purpose: Activates NIC configuration, enables data transmission and reception, performs minimal operability check.

Syntax: int hcf_enable( IFBP ifbp,
hcf_16 port );

Returns: HCF_SUCCESS
HCF_ERR_NO_NIC
HCF_ERR_INCOMP_PRI
HCF_ERR_INCOMP_STA
HCF_ERR_TIME_OUT
HCF_ERR_LEN
HCF_FAILURE

Parameters:

Entry
Ifbp	Value indicating the address of the IFB Values: Address Þ Any value
Port	Number indicating the MAC Port MAC Port Values: · MAC Port 0 Þ HCF_PORT_0 ================ HCF only section (start) ================ · MAC Port 1 Þ HCF_PORT_1 · MAC Port 2 Þ HCF_PORT_2 · MAC Port 3 Þ HCF_PORT_3 · MAC Port 4 Þ HCF_PORT_4 · MAC Port 5 Þ HCF_PORT_5 · MAC Port 6 Þ HCF_PORT_6 ================ HCF only section (end) ================

Exit
Return Value	Number indicating the function execution result Values: Success Ü HCF_SUCCESS No card present in slot Ü HCF_ERR_NO_NIC Primary functions firmware not compatible Ü HCF_ERR_INCOMP_PRI Station functions firmware not compatible Ü HCF_ERR_INCOMP_STA Timer calibration failed Ü HCF_ERR_TIME_OUT Error in retrieving compatibility information from card Ü HCF_ERR_LEN Hermes failure or HCF bug Ü HCF_FAILURE
Ifb	Fields affected: · IFB_CardStat CARD_STAT_ENABLED Ü set · IFB_DUIFRscInd Ü 1 · IFB_NotifyRscInd Ü 1 · IFB_PIFRscInd Ü 1
Interrupts	NIC interrupts enabled.

Description:

The hcf_enable command is likely to change when the MAC Port mechanism is implemented

When hcf_enable is called while the NIC is not present, the Enable function does not result in I/O actions. These actions will be postponed till the MSF calls hcf_action( HCF_ACT_CARD_IN ) when the NIC is inserted.

The NIC hardware (i.e. Memory, Hermes, etc.) is initialized in accordance with the NIC Configuration settings in non-volatile NIC memory, possibly augmented by the accumulated effects of preceding hcf_put_info calls.

The NIC interrupts are set according to the nesting level of HCF_ACT_INT_OFF/ON commands. Since hcf_connect defaults to HCF_ACT_INT_OFF, MSFs using a polled strategy do not need additional actions. MSFs based on an interrupt strategy must call hcf_action with HCF_ACT_INT_ON either before or after hcf_enable.

The HCF housekeeping is initialized, e.g. the Transmit Resource, the Driver-Utility I/F resource, and the Notify resource are acquired.

During this reset, initialization, and configuration process, the response of the NIC on the individual commands is observed. If the expected behavior does not occur a "Failure" indication is returned, otherwise a "Success" indication. This is a light-weight form of diagnostics. A more thorough test with a more detailed result reporting can be achieved by calling function hcf_action with code HCF_ACT_DIAG.

The very first call to hcf_enable may calibrate the HCF timer mechanism through an indirect call to hcf_disable. To make this calibration as accurate as possible, it may help to disable all interrupts prior to this first call of hcf_enable.

The HCF housekeeping is prepared for the first/next Put Data Function (see Appendix 12.8).

hcf_enable must be called after:

• Some of the commands used with hcf_put_info (see Appendix 12.9)
• Some of the commands used with hcf_action (see Appendix 12.1)

 

Assert fails if

• ifbp is zero or other recognizable out-of-range value.
• hcf_enable is called without prior call to hcf_connect.
• card is busy with a download, or a diagnose command.
• port is out of range

2. GET DATA FUNCTION ( hcf_get_data )

Purpose: Obtains received message data parts or control information from the Card.

Syntax: int hcf_get_data( IFBP ifbp,
int offset,
wci_bufp *datbuf,
int datlen );

Returns: HCF_SUCCESS
HCF_ERR_NO_NIC

Parameters:

Entry
ifbp	Value indicating the address of the I/F Block Values: Address Þ Any value
offset	Value specifying the beginning of the data part or the control information to be obtained. Values: Data Offset Þ 0 - 0x7FFF Control Information offset Þ HFS_STAT – HFS_ID(-0x2E - -0x1E ) How about 802.11
datbuf	Pointer to the Data Buffer location. Values: Buffer location Þ Address pointer
datlen	Value specifying the number of message bytes to be obtained. Values: Data Length Þ 0 - 0x7FFF
Interrupts	NIC interrupts disabled.

Exit
Return Value	Enumerated value indicating the Read Status. Values: Success Ü HCF_SUCCESS Card removed during data Retrieval Ü HCF_ERR_NO_NIC

 

Description:

Starting at the byte indicated by the positive Offset value (e.g.: at the first message byte if the offset is HFS_DAT), the bytes are copied from the current Receive Frame Structure to the Data Buffer. Due to the Data Offset parameter, the MSF does not need to read the NIC RAM buffer in consecutive chunks. The most likely application of this feature, is reading part of the message and then starting all over based on directions the MSF receives from the higher levels in the Protocol Stack.

Starting at the byte indicated by the negative Offset value (e.g.:

Copying stops if the number of bytes indicated by the Data Length value are copied.

If the number of message bytes following the byte indicated by the Data Offset is less than the Data Length value, the remaining bytes of the Data Buffer structure are undefined.

If an error is detected (i.e. when the PCMCIA Card is removed), HCF_ERR_NO_NIC is returned. Otherwise, "Success" is returned. The most likely handling of a read error by the MSF is to drop the already copied data as elegantly as possible under the constraints and requirements posed by the (N)OS. If no received Frame Structure is pending, "Success" rather than "Read error" is returned. This error constitutes a logic flaw in the MSF. The HCF can only catch a minority of this type of errors. Based on consistency ideas, the HCF catches none of these errors.

 

Assert fails if

• ifbp is zero or other recognizable out-of-range value.
• datbufp is a NULL pointer.
• hcf_get_data is called without prior call to hcf_connect.
• interrupts are enabled.
• No resources for data reception are available.
• Data Offset is not within the Receive Transmit Structure.
• Data Offset + Data Length is not within the Receive Transmit Structure.

 

2. GET INFORMATION FUNCTION ( hcf_get_info )

Purpose: Obtains information from the NIC.

Syntax: int hcf_get_info( IFBP ifbp,
LTVP ltvp );

Returns: HCF_SUCCESS
HCF_FAILURE
HCF_ERR_LEN
HCF_ERR_NO_NIC
HCF_ERR_TIME_OUT

Parameters:

Entry
ifbp	Value indicating the address of the I/F Block Values: Address Þ Any value
ltvp	Pointer to an LTV-record in PC-RAM. Values: Buffer location Þ Address pointer
Interrupts	Card interrupts disabled

Exit
Return Value	Success Ü HCF_SUCCESS Unspecified error Ü HCF_FAILURE The buffer provided in datbfp was too small Ü HCF_ERR_LEN Card removed during retrieval Ü HCF_ERR_NO_NIC Hermes did not respond timely Ü HCF_ERR_TIME_OUT

 

Description:

At the time hcf_get_info is called, the L-field of the LTV-record (provided by the MSF in parameter ltvp) specifies the size of the buffer, also called the "Initial DataLength". The L-value should include the size of the T-field, but not the size of the L-field. The T-field specifies the RID wanted.

Depending on the value of the T-field in the LTV-record the HCF supplies the requested information either synchronously or asynchronously in the V-field. In both cases the L-field on return indicates the number of words actually contained by the Type and Value fields.

Synchronous information

The RID information identified by the T-field is copied into the V-field. As the size of the Type field in the LTV-record is included in the "Initial Datalength" of the record, the V-field can contain at most "Initial DataLength" - 1 words of data.

Asynchronous information

Asynchronous information is only supported by the HCF.

 

 

It is the responsibility of the MSF to detect card removal and re-insertion and inform the HCF accordingly. The MSF can not, however, timely report a Card removal to the HCF if the Card is removed while the hcf_get_info is in progress. Therefore, the HCF performs its own check on Card presence after the read operation of the NIC data. If the Card is not present or removed during the execution of hcf_get_info, HCF_ERR_NO_NIC is returned and the contents of the Data Buffer is unpredictable.

Copying stops if either the complete Configuration or Operation Information is copied or if the number of words indicated by the "Initial DataLength" were copied. The "Initial DataLength" 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. If the size of Value field of the RID exceeds the size of the "Initial DataLength" -1, as much data as fits is copied, and an error status of HCF_ERR_LEN is returned.

Assert fails if

• ifbp is zero or other recognizable out-of-range value.
• ltvp is a NULL pointer.
• hcf_get_info was called without a prior call to hcf_connect.
• hcf_get_info was called with typ-field in ltvp other than CFG_MB_INFO while a download is active.
• type field of the LTV-record is invalid.
• length field of the LTV-record at entry is 0 or 1.

 

2. PUT DATA FUNCTION ( hcf_put_data)

Purpose: Transfers transmit message data parts or control information to the Card.

Syntax: void hcf_put_data( IFBP ifbp,
wci_bufp *datbuf,
int datlen,
hcf_16 port );

Returns: N/A

Parameters:

Entry
Ifbp	Value indicating the address of the I/F Block Values: Address Þ Any value
Datbuf	Pointer to the Data Buffer location. Values: Buffer location Þ Address pointer
Datlen	Value specifying the number of message bytes to be transferred. Values: Data Length Þ 0 - 0x7FFFF
Port	Number indicating the MAC Port MAC Port Values: · MAC Port 0 Þ HCF_PORT_0 ================ HCF only section (start) ================ · MAC Port 1 Þ HCF_PORT_1 · MAC Port 2 Þ HCF_PORT_2 · MAC Port 3 Þ HCF_PORT_3 · MAC Port 4 Þ HCF_PORT_4 · MAC Port 5 Þ HCF_PORT_5 · MAC Port 6 Þ HCF_PORT_6 · Discard preceding data Þ HCF_PUT_DATA_RESET ================ HCF only section (end) ================
Interrupts	NIC interrupts disabled.

Exit
	N/A

 

Description:

Add 802_3_PURE, HCF_PORT_6 and HCF_PUT_DATA_RESET description

hcf_put_data transfers header or control information or (part of) a transmit message from the provided buffer structure to the Transmit Frame Structure. The information can be transferred in one or more calls. The data associated with subsequent hcf_put_data calls are concatenated to the data of the preceding call. Hence, the fragments which constitute the header and the data must be written in sequence. Hcf_put_data maintains housekeeping information over subsequent calls. This housekeeping information is reset by functions hcf_send and hcf_enable. In case of the HCF, the housekeeping information can also be reset by calling hcf_put_data with HCF_PUT_DATA_RESET as parameter.

The way in which hcf_put_data has to be used depends on the type of message to be sent:

• 802.3 frames

All information of an 802.3 frame, i.e. the addressing information, the data length, and the actual message, should be transferred to the Transmit Frame structure by means of hcf_put_data calls. The data associated with the first hcf_put_data call (after resetting the housekeeping information), is stored from position HFS_ADDR_DEST onwards. The datalength/type field should not be split over two hcf_put_data calls.

• Ethernet-II frames

When in 802_3 mode (the default mode, explicitly controlled by hcf_action with HCF_ACT_802_3 as parameter), encapsulation of Ethernet-II frames is supported. All information of an Ethernet-II frame should be transferred to the Transmit Frame structure in the same way as for an 802.3 frame. Hcf_put_data distinguishes between an 802.3 and an Ethernet-II frame by looking at the datalength/type field of the frame. If this field contains a value larger than 1514, the frame is considered to be an Ethernet-II frame, otherwise it is treated as an 802.3 frame. This test fails if the datalength/type field is split over two hcf_put_data calls.

The HCF contains a table (enc_trans_tbl) which stores a number of types. If the value specified by the datalength/type field occurs in this table, Bridge Tunnel Encapsulation is used, otherwise RFC1042 encapsulation is used.

An Ethernet-II frame is treated like an 802.3 frame, but additionally a SNAP header is inserted between the addressing information and the type field. This insertion is transparent for the MSF.

• 802.11 frames

All information of an 802.3 frame, i.e. the addressing information, the data length, and the actual message, should be transferred to the Transmit Frame structure by means of hcf_put_data calls. It is allowed to write the 802.11 header in fragments, e.g. the first hcf_put_data call writes 18 bytes (starting at location HFS_ADDR_1), the second call writes 6 more bytes (starting at location HFS_ADDR_4). Even if the 802.11 header does not contain all 4 addressing parts, the unused parts must be written. The data supplied for these unused parts is immaterial. Once the complete header has been written, the data part should be transferred by one or more calls to hcf_put_data.

The algorithm to distinguish between 802.3 and Ethernet-II frames limits the maximum length for frames of 802.3 frames to 1514 bytes.

Copying stops if either the number of bytes indicated by the Data Length value have been copied into the data buffer structure, or the end of the Transmit buffer in NIC RAM is reached. Hcf_put_data does not check for transmit buffer overflow, because the Hermes does this protection. In case of a transmit buffer overflow, the surplus which does not fit in the buffer is simply dropped.

Refer to the introductory part of 5.3 for the relationship between the Put Data Function and the Command Resource Indicator (IFB_PIFRscInd).

The functions hcf_put_data and hcf_send are biased to make their use "easy" for 802.3 frames.

Assert fails if

• ifbp is zero or other recognizable out-of-range value
• datbufp is a NULL pointer
• hcf_put_data is called without prior call to hcf_connect.
• No resources are available.
• Interrupts are enabled.
• Data Offset is not within the Frame Structure
• Data Offset is in the 802.11 address/control/data area, and Data Offset + Data Length is not
• Put Data is called and not either
• preceded by another Put Data call since the last Send Data
  or
• the command resource indicator is zero and it is the first Put Data call since the last Send Data
• the command resource indicator is non-zero, and the Put Data function is preceded by another Put Data call (with non-zero length) since the last Send Data. If this occurs ever, this is an error which is not caused by the MSF but an HCF bug.

2. PUT INFORMATION FUNCTION ( hcf_put_info )

Purpose: Transfers information to the NIC.

Syntax: int hcf_put_info( IFBP ifbp,
LTVP ltvp );

Returns: HCF_SUCCESS
HCF_FAILURE
HCF_ERR_NO_NIC
HCF_ERR_LEN
HCF_ERR_TIME_OUT

Parameters:

Entry
ifbp	Value indicating the address of the I/F Block. Values: Address Þ Any value
ltvp	Pointer to an LTV-record in PC-RAM. Values: Buffer location Þ Address pointer
Interrupts	Card interrupts disabled

Exit
	Success Ü HCF_SUCCESS Unspecified error Ü HCF_FAILURE Not enough room to store the information Ü HCF_ERR_LEN Card removed during writing information Ü HCF_ERR_NO_NIC Hermes did not respond timely Ü HCF_ERR_TIME_OUT

 

Description:

The L-field of the LTV-record (provided by the MSF in parameter ltvp) specifies the size of the buffer. The L-value should include the size of the T-field, but not the size of the L-field. The T-field specifies the RID placed in the V-field by the MSF.

Not all CFG-codes can be used for hcf_put_info. The following CFG-codes are valid for hcf_put_info:

• One of the CFG-codes in the group "Network Parameters, Static Configuration Entities" (see Appendix 10)

Changes made by hcf_put_info to CFG_codes in this group will not affect the Hermes and HCF behavior until hcf_enable is called .

• One of the CFG-codes in the group "Network Parameters, Dynamic Configuration Entities" (see Appendix 10.2)

Changes made by hcf_put_info to CFG_codes will affect the Hermes and HCF behavior immediately.

All LTV-records "unknown" to the HCF are ignored and cause an HCFASSERT.

Network parameters

When hcf_put_info is called with one of the CFG-codes of the Network Parameters, these parameters are in addition to being written to the NIC, also stored in the Configuration Table. The Configuration Table in the IFB (see section 4.4.3) is scanned whether that particular CFG-code is already present. If so, that information is removed. The new information will only be copied into the Configuration Table in the IFB if there is enough room in the IFB. If the space in the Configuration Table does not suffice, hcf_put_info does not take any further action (other than an Assert).

As opposed to hcf_get_info, NIC removal during the write process is not considered an error. Also the MSF is allowed to call hcf_put_info when no card is present. If a Configuration Table of suitable size is defined, the HCF will transfer the information when the NIC is re-inserted.

The check whether the record fits in the Configuration Table is the only validation done on the information in the LTV-record, e.g. no test is done whether the number of Multicast addresses exceeds the allowed maximum value.

Assert fails if

• ifbp is zero or other recognizable out-of-range value.
• ltvp is a NULL pointer.
• hcf_put_info was called without prior call to hcf_connect
• type field of the LTV-record is invalid.
• length field of the LTV-record at entry is less than 1.
• not enough room in the Configuration Table in the IFB to store the information.
• type field indicates storage in MailBox and no MailBox is registered.
• a non-download HCF-command is given before the download sequence is completed.
• registering a MailBox with size less than 60.
• CFG_DLV_ADDR is given without preceding CFG_DLV_START .
• CFG_DLV_DATA is given without preceding CFG_DLV_ADDR.
• CFG_DLV_STOP is given without preceding CFG_DLV_ADDR/CFG_DLV_DATA pair.
• CFG_DLNV_DATA is given without preceding CFG_DLNV_START.
• CFG_DLNV_STOP is given without preceding CFG_DLNV_DATA.

 

2. RESEND FUNCTION ( hcf_resend )

The Resend Function is applicable for the HCF only.

 

3. Put Header FUNCTION (hcf_put_header )

The Put Header Function is applicable for the HCF only.

 

5. SEND FUNCTION ( hcf_send )

Purpose: Initiates transmission of a message.

Syntax: int hcf_send( IFBP ifbp
hcf_16 port );

Returns: ???

Parameters:

Entry
ifbp	Value indicating the address of the I/F Block Values: Address Þ Any value
Port	Number indicating the MAC Port Currently not used
Interrupts	NIC interrupts disabled.

Exit
	Add DataCorruptionWorkAround ???

 

Description:

The transmitter of the Card is activated to send the appropriate Header Info area and the Data Info area. The first word of the Data Info area specifies the data length to the Hermes. The Data Info area as well as the appropriate (802.3 or 802.11) Header Info area must have been written to the Transmit Frame Structure by one or more preceding hc_put_data calls.

The hcf_put_data and hcf_send function are biased to make their use "easy" for 802.3 frames. More details are given in 12.8.

In addition, the HCF housekeeping is prepared for the next Put Data Function.

Two calls of the Send Function without at least one intervening call to the Put Data function results in undefined behavior.

Assert fails if

• ifbp is zero or other recognizable out-of-range value.
• type is invalid.
• hcf_send is called while a download or diagnose command is active.
• two calls to hcf_send in a row without intervening hcf_put_data call(s).

2. SEND DIAGNOSTIC MESSAGE FUNCTION
   ( hcf_send_diag_msg )

This function is supported by the HCF only

 

4. SERVICE NIC FUNCTION ( hcf_service_nic )

Purpose: Services NIC events and provides status information.

Syntax: int hcf_service_nic( IFBP ifbp );

Returns: 0 or a combination of one or more of the values below:
HREG_EV_TICK
HREG_EV_WT_ERR
HREG_EV_INFO_DROP
HREG_EV_NO_CARD
HREG_EV_DUIF_RX
HREG_EV_INFO
HREG_EV_CMD
HREG_EV_ALLOC
HREG_EV_TX_EXC
HREG_EV_TX
HREG_EV_RX

Parameters:

Entry
ifbp	Value indicating the address of the I/F Block Values: Address Þ Any value
Interrupts	NIC interrupts disabled

Exit
ifbp	Fields affected: IFB_MBInfoLen Reflects the L-field of the oldest MBIB. Values: No data available Ü 0 Info Length Ü 2 - 0x7FFF IFB_RxLen Specifying the number of message bytes available in the current Receive Frame Structure (excluding address information, length, and sum check) Values: No message available Ü 0 Data Length Ü 14 - 0x7FFF IFB_RxStat Code indicating the Receive Error Status if Monitor Mode is On Values: Success Ü 0 No available message Ü 0 CRC Error Ü HCF_ERR_CRC Alignment Error Ü HCF_ERR_ALIGN Resource Error Ü HCF_ERR_RSC Too Short Error Ü HCF_ERR_RUNT
Return Value	Interrupt cause Values: Rx Ü HREG_EV_RX Tx Ü HREG_EV_TX TxExc Ü HREG_EV_TX_EXC Alloc Ü HREG_EV_ALLOC Cmd Ü HREG_EV_CMD Tal Ü HREG_EV_TAL Info Ü HREG_EV_INFO Ü HREG_EV_NO_CARD RxWMP Ü HREG_EV_RXWMP Tick Ü HREG_EV_TICK

 

 

xx: Decapsulation is NOT done in case of:

- WMP messages transferred to the MailBox

- IFB_FrameType == HCF_ACT_802_3_PURE or HCF_ACT_802_11

- erroneous frame in case of promiscuous mode

Decapsulation is done in case of error free frame in promiscuous mode

Description:

The HCF handles most of the processing associated with NIC interrupts. The MSF plays a role in the receiver interrupt and info event interrupt processing. It is also the responsibility of the MSF to perform all not directly NIC related interrupt service actions, e.g. in a PC environment this includes servicing the PIC, and managing the Processor Interrupt Enabling/Disabling.

The Service NIC Function must be executed by the MSF ISR to determine the interrupt cause(s). It checks if a usable Receive Frame Structure is available in Card memory. If a Receive Frame Structure is available, the Received Data Length field IFB_RxLen (see section 4.3.1) contains a non-zero value, indicating the message length (excluding address information, length, and sum check).

The status bits of Received Status field IFB_RxStat are zero if no message or a correct message was received. In case Monitor Mode is On and an erroneous message was received, IFB_RxStat qualifies the error.

The port bits of Received Status field IFB_RxStat………………………………………

Repeated execution causes the Service NIC Function to provide information about subsequently received messages, irrespective if the Get Data Function is performed in between. Hcf_service_nic must be called repeatedly until IFB_RxLen has a zero value.

hcf_service_nic returns:

• The length of the data in the available Receive Frame Structure (IFB_RxLen)
• The length of the data in the available MBIB (IFB_MBInfoLen)
• The status of a message received in Network Monitor mode (IFB_RxStat). The values for HCF_ERR_CRC, HCF_ERR_ALIGN, HCF_ERR_RSC, and HCF_ERR_RUNT are customizable via HCFCFG.H.
• a status reflecting:
• a log of all Hermes events noticed during the call to hcf_service_nic.
• indication of NIC presence or absence.
• indication of WMP message processing.

The format of the Hermes event log is based on the bit-layout of the Hermes EvStat register. Every event which has been seen during the hcf_service_nic activity, raises the corresponding bit in the return status of hcf_service_nic.

The indication of NIC presence or absence, and the indication of WMP message processing are - from the MSF viewpoint - comparable to Hermes events, therefore these events are indicated by two bits which correspond with two of the free bits in the Hermes EvStat register.

The purpose of the return status is purely to help during the debugging process. MSFs must base their strategy on IFB-fields like IFB_RxLen, and IFB_MBInfoLen, and not on the return status.
HREG_EV_TAL is assumed not to be needed once tally overflow results in an info event look alike event.

Since the MSF must have its own mechanism to detect NIC removal/insertion, and take action to recover from NIC removal/re-insertion (see hcf_disable/hcf_enable), the MSF is not allowed to use HREG_EV_NO_CARD.

The MSF is not expected to be sensitive to the HREG_EV_RXWMP bit, because the HCF ( in non-Monitor Mode) discards all WMP frames after processing.

The meaning of the individual bits in the return status of hcf_service_nic as generated by the Hermes and the HCF is given in the table below.

Table 16 hcf_service_nic return status bits

Bit	Generator	Meaning
HREG_EV_TICK	Hermes	Occurs at each tick of the Auxiliary timer.
HREG_EV_INFO	Hermes	Occurs when an Information frame is generated by an asynchronous process.
HREG_EV_CMD	Hermes	Occurs when command execution is completed.
HREG_EV_ALLOC	Hermes	Occurs when a buffer for a Transmit Frame Structure is allocated or reclaimed.
HREG_EV_INFO_DROP	Hermes	Occurs when WMAC did not have sufficient RAM to build an Unsolicited Frame for an asynchronous process.
HREG_EV_ENG	Hermes	Hermes Development Engineering Purposes only
HREG_EV_TX_EXC	Hermes	Due to the configuration of the Hermes by the WCI, this event does not occur in WCI based Host S/W. The meaning of this status is: "asynchronous Transmission process is unsuccessfully completed".
HREG_EV_TX	Hermes	Due to the configuration of the Hermes by the WCI, this event does not occur in WCI based Host S/W. The meaning of this status is: "asynchronous Transmission process is successfully completed".
HREG_EV_RX	Hermes	Occurs when a frame is received by the asynchronous Reception process.
HREG_EV_WT_ERR	Hermes	Hermes Development Engineering Purposes only
HREG_EV_NO_CARD	HCF	Occurs when the safety check performed by the HCF detects that the NIC is removed while not yet an hcf_disable command was executed.
HREG_EV_DUIF_RX	HCF	Occurs when a WMP frame is received by asynchronous reception and the Status-field of the Receive Frame Structure reflects that the frame is a WaveLAN Management Protocol frame.

Table 16 hcf_service_nic return status bits

When IFB_RxLen is non-zero, a Received Frame Structure is available to be routed to the protocol stack. When Monitor Mode is not active, this is guaranteed to be an error-free non-WMP frame. In case of Monitor Mode, it may also be a frame with an error or a WMP frame. Erroneous frames have a non-zero IFB_RxStat field. WMP frames are not recognizable, without checking the contents of the frame itself (i.e. the Status field of the Control Field or the SNAP header of the Data Info field)

When IFB_MBInfoLen is non-zero, at least one MBIB is available. The handling of this Frame Structure depends on its type, which is one of the following:

• Tally Event
  The HCF accumulates the 16 bits wide Hermes tallies in its own 32 bits wide structure.
• Link Event
  The Inquiry frame or Unsolicited Information frame is copied into the MailBox. If IFB_MBInfoLen field is zero, this field is updated. The HREG_EV_INFO event is acknowledged.

 

Hcf_service_nic takes the following actions:

• Process all Hermes events which can be handled without additional MSF support. This are all events except HREG_EV_RX. HREG_EV_RX is handled different compared with the other Hermes events.
• The HREG_EV_RX event is acknowledged by the first hcf_service_nic call after the hcf_service_nic call which reported the occurrence of this event. This acknowledgment makes the next Receive Frame Structure (if any) available. This availability is reflected by an updated IFB_RxLen field.

Assert fails if

• ifbp is zero or other recognizable out-of-range value.
• hcf_service_nic is called without a prior call to hcf_connect.
• interrupts are enabled.

 

2. ASSERT FUNCTION (msf_assert)

The assert function is supported by the HCF only

1. APPENDIX J - WCI FUNCTIONS REFERENCE CHARTS

• These charts list for each of the WCI Functions a short purpose description, the input parameters and return values passed as C function arguments, and the WCI Design Specification page number where the Functional Description can be found.

NIC CONFIGURATION GROUP

C Declaration Syntax	Return code	Purpose	Page
int hcf_enable(	HCF_SUCCESS HCF_ERR_NO_NIC HCF_ERR_INCOMP_PRI HCF_ERR_INCOMP_STA HCF_ERR_TIME_OUT HCF_ERR_LEN HCF_FAILURE	Activates NIC configuration, enables data transmission and reception, performs minimal operability check.	*
int hcf_disable( IFBP ifbp, hcf_16 port );	HCF_SUCCESS HCF_ERR_NO_NIC HCF_ERR_INCOMP_PRI HCF_ERR_INCOMP_STA HCF_ERR_TIME_OUT HCF_ERR_LEN	Disables data transmission and reception.	*
int hcf_action( IFBP ifbp, hcf_action_cmd cmd );	HCF_SUCCESS HCF_FAILURE (;?cmd_wait) HCF_ERR_TIME_OUT (;?cmd_wait) HCF_INT_PENDING	Changes the run-time NIC behavior controlled by the binary NIC Configuration settings.	*
int hcf_get_info( IFBP ifbp, LTVP ltvp );	HCF_SUCCESS HCF_FAILURE HCF_ERR_LEN HCF_ERR_NO_NIC HCF_ERR_TIME_OUT	Obtains information from the NIC.	*
int hcf_put_info( IFBP ifbp, LTVP ltvp );	HCF_SUCCESS HCF_FAILURE HCF_ERR_NO_NIC HCF_ERR_LEN HCF_ERR_TIME_OUT	Transfers information to the NIC.	*

 

 

DATA TRANSFER GROUP

C Declaration Syntax	Return code	Purpose	Page
int hcf_service_nic( IFBP ifbp );	0 or a combination of one or more of the values below: HREG_EV_TICK HREG_EV_WT_ERR HREG_EV_INFO_DROP HREG_EV_NO_CARD HREG_EV_DUIF_RX HREG_EV_INFO HREG_EV_CMD HREG_EV_ALLOC HREG_EV_TX_EXC HREG_EV_TX HREG_EV_RX	Services NIC events and provides status information.	*
int hcf_get_data( IFBP ifbp, int offset, wci_bufp *datbuf, int datlen );	HCF_SUCCESS HCF_ERR_NO_NIC	Obtains received message data parts or control information from the Card.	*
void hcf_put_data( IFBP ifbp, wci_bufp *datbuf, int datlen, hcf_16 port );	N/A	Transfers transmit message data parts or control information to the Card	*
int hcf_send( IFBP ifbp hcf_16 port );	???	Initiates transmission of a message.	*
Error! Reference source not found.	Error! Reference source not found.	Error! Reference source not found.	*
Error! Reference source not found.	Error! Reference source not found.	Error! Reference source not found.	*

 

 

NIC CONNECTION GROUP

C Declaration Syntax	Return code	Purpose	Page
void hcf_connect( IFBP ifbp, hcf_io io_base );	N/A	Initializes the HCF housekeeping part of the IFB. Grants access right for the HCF to the IFB	*
void hcf_disconnect( IFBP ifbp );	N/A	Disables data transfer and releases the IFB. Revokes access right from the HCF to the IFB	*

 

MSF SUPPORT GROUP

C Declaration Syntax	Return code	Purpose	Page
Error! Reference source not found.	Error! Reference source not found.	Error! Reference source not found.	*