HomeProjectsPeoplePublicatons
Search:
   
 

Wireless Communications and Networking Division

   

Doc. No.

S0005 Rev. 11

 

DRAFT

Software Interface Specification

for

Wireless Connection Interface for WaveLAN/IEEE

(HCF-light)

 

 

 

Prepared By:

Nico Valster

Date:

10/11/99

 

Systems Analyst

   
   

Approved By:

 
       

WaveLAN/IEEE System Team

 

Leo Monteban

Date:

 
 

Team Captain

   
       

Other

 

Date:

 
       
       
 

This document and information herein is the property of Lucent Technologies Inc. and all unauthorized use and reproduction is prohibited.

Copyright ã 1999 Lucent Technologies Inc.

All rights reserved. Confidential, Unpublished Property of Lucent Technologies Inc.

CONCURRENCE

 

       
   

Date:

 
       
 

 

 

CHANGE SHEET

   

Description of change

Appr.

Rev.

Date

Page

Par.

 

Date

1

ddMmmyy

all

all

Initial issue (X.Xxxxxx)

Optional reference to source material (e.g. Design Notes)

 

2

11SEP97

7-9

44-48

70

 

Descriptions related to the Mailbox and Mailbox functions added

 

6

23JAN98

   

Description of download process added. Description of function hcf_get_info and hcf_put_info accordingly.

 

7

?????98

all

all

Complete update to reflect changes in HCF.

 

10

14JAN99

all

all

Complete update to reflect changes in HCF.

 

11

17FEB99

All

all

Preliminary release for the HCF-light audience. Focus is on concepts. The details, especially the functional description, function error codes and return information in Appendix I may be incomplete or even incorrect / out of date / not up to date. The need to disseminate the information contained in this document is considered to overrule the aspect of perfection.

 
           
           
           
           
           
           
           

table of contents

1. Executive summary *

2. reference documents *

2.1 WaveLAN/IEEE Documents *

3. overview *

3.1 Disclaimer *

3.2 HCF versus HCF-light *

3.3 Network Operating Systems Environment *

4. Interfaces *

4.1 Syntax conventions *

4.2 Code Adaptation Controls *

4.2.1 System Constants *

4.2.2 System Macros and Typedefs *

4.3 Information Transfer *

4.3.1 I/F Block Concept *

4.3.2 LTV Record Concept *

4.3.3 Hermes Record Concept *

4.3.4 Configuration Table concept *

4.3.5 MailBox Concept *

4.3.6 Download concept *

4.4 Data Structures *

4.4.1 IFB *

4.4.2 LTV Records *

4.4.3 Configuration Table *

4.4.4 Receive and Transmit Frame Structures *

4.5 Data structures and Input/Output Customization *

4.5.1 Transmit/Receive Frames *

4.5.2 LTV-records *

4.5.3 IN_PORT_WORD(port) *

4.5.4 OUT_PORT_WORD(port, value) *

4.5.5 Void IN_PORT_STRING( port, dest, len) *

4.5.6 void OUT_PORT_STRING( port, src, len) *

4.5.7 common notes for IN_PORT_STRING and OUT_PORT_STRING *

5. functional descriptions *

5.1 Connection Group *

5.2 NIC Configuration Group *

5.3 Data Transfer Group *

5.4 MSF Support Routines *

6. Implementation Notes *

6.1 AccessPoint/Station functionality *

6.2 Alignment restrictions *

6.3 Polled control *

6.4 Interference control *

6.5 Connect/Disconnect control *

6.6 Transmission control *

6.7 NIC Configuration *

6.8 NIC Modes *

6.8.1 NIC Interrupts (Enabled/Disabled) *

6.8.2 Card presence (In/Out) *

6.8.3 Timer tick interrupts (On/Off) *

6.8.4 Frame type (802.11/802.3/802.3 pure) *

6.9 Card Swap *

6.10 ISR *

6.11 C / C++ *

6.12 Reset *

6.13 Memory use *

6.14 Notify Control *

6.15 Download *

6.16 msf_assert *

6.17 Blocking *

6.18 MSF_COMPONENT_…. and DUI_COMPAT_…… *

6.19 Exclusions *

6.20 User scenarios *

6.21 Pitfalls *

7. APPENDIX A - HCF SOURCE CODE LIBRARY *

7.1 Appendix A.1 - Information Files *

7.2 Appendix A.2 - Template Files *

7.3 Appendix A.3 - Code Generation Files *

8. Appendix B - HCF defined LTV-Records *

9. Appendix C - Hermes - HCF Record Correlation *

9.1 Configuration RIDs *

9.2 Information RIDs *

10. Appendix D: Configuration parameters *

10.1 Network Parameters, Static Configuration Entities *

10.1.1 cnfPortType *

10.1.2 cnfOwnMACAddress *

10.1.3 cnfDesiredSSID *

10.1.4 cnfOwnChannel *

10.1.5 cnfOwnSSID *

10.1.6 cnfOwnATIMWindow *

10.1.7 cnfSystemScale *

10.1.8 cnfMaxDataLength *

10.1.9 cnfWDSAddress *

10.1.10 cnfPMEnabled *

10.1.11 cnfPMEPS *

10.1.12 cnfMulticastReceive *

10.1.13 cnfMaxSleepDuration *

10.1.14 cnfPMHoldoverDuration *

10.1.15 cnfOwnName *

10.1.16 cnfOwnDTIMPeriod *

10.1.17 CnfWDSAddress1..6 *

10.1.18 CnfMulticastPMBuffering *

10.2 Network Parameters, Dynamic Configuration Entities *

10.2.1 GroupAddresses *

10.2.2 CreateIBSS *

10.2.3 FragmentationThreshold *

10.2.4 RTSThreshold *

10.2.5 TxRateControl *

10.2.6 PromiscuousMode *

11. Appendix E - Data structures *

12. Appendix F - Function descriptions *

12.1 ACTION FUNCTION ( hcf_action ) *

12.2 CONNECT FUNCTION ( hcf_connect ) *

12.3 DISABLE FUNCTION ( hcf_disable ) *

12.4 DISCONNECT FUNCTION ( hcf_disconnect ) *

12.5 ENABLE FUNCTION (hcf_enable ) *

12.6 GET DATA FUNCTION ( hcf_get_data ) *

12.7 GET INFORMATION FUNCTION ( hcf_get_info ) *

12.8 PUT DATA FUNCTION ( hcf_put_data) *

12.9 PUT INFORMATION FUNCTION ( hcf_put_info ) *

12.10 RESEND FUNCTION ( hcf_resend ) *

12.11 Put Header FUNCTION (hcf_put_header ) *

12.12 SEND FUNCTION ( hcf_send ) *

12.13 SEND DIAGNOSTIC MESSAGE FUNCTION ( hcf_send_diag_msg ) *

12.14 SERVICE NIC FUNCTION ( hcf_service_nic ) *

12.15 ASSERT FUNCTION (msf_assert) *

13. APPENDIX J - WCI FUNCTIONS REFERENCE CHARTS *

FIGURES

 

Figure 2 Frame structures formats *

 

TABLES

Table 1 HCF and HCF-light System Constants *

Table 3 HCF and HCF-light System Macros *

Table 5 Layout of LTV-records *

Table 6 Correlation frame type, hcf_get_data offset parameter and offsets *

Table 7 Macros for optimization of string I/O *

Table 8 Information Files *

Table 9 Template Files *

Table 10 Code Generation File *

Table 12 Network Parameters, Static Configuration Entities *

Table 13 Network Parameters, Dynamic Configuration Entities *

Table 14 Behavior Parameters *

Table 15 NIC Information *

Table 16 MAC Information *

Table 17 Modem Information *

Table 18 MSF readable parts of the IFB *

Table 19 hcf_service_nic return status bits *

???hcf_debug_trigger???

  1. Executive summary

This document describes a source code library, which provides a consistent interface to the Lucent Technologies 802.11 MAC Controller, called Hermes, and used in the WaveLAN/IEEE environment. This interface is called the Wireless Connection Interface or WCI. The implementation of the WCI is called the Hardware Control Functions.

There are two implementations of the Hardware Control Functions, called HCF and HCF-light respectively. HCF-light is a subset of the HCF, intended for the Public Domain while the HCF is proprietary.

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

Using WCI, a programmer can create drivers to control Network Interface Cards (NIC) based on the Hermes (ref. 4). The code written on top of the WCI is called the Module Specific Functions, or MSF. The MSF code must supply support to the HCF for:

  • 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
    2. 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

       

    3. overview
      1. Disclaimer
      2. 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.

         

      3. 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,

      1. Code Adaptation Controls
        1. System Constants
        2. 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

         

      2. 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
        2. 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.

           

        3. Configuration Table concept
        4. The Configuration Table concept is applicable for the HCF only.

           

        5. MailBox Concept
        6. The MailBox concept is applicable for the HCF only.

           

        7. Download concept

    The Download concept is applicable for the HCF only.

     

      1. Data Structures
      2. 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
        2. The Configuration Table concept is applicable for the HCF only.

           

        3. 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

      1. 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
        2. 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).

           

        3. 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)
        2. 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.

           

        3. 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

    1. functional descriptions
    2. 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
      2. 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.

         

      3. 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
      2. 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.

         

      3. MSF Support Routines

    The MSF Support Routines are applicable for the HCF only.

     

     

    1. Implementation Notes
    2. 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
      2. 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.

      3. Polled control
      4. 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.)

         

      5. 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
      2. 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.

         

      3. 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
      2. 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.

         

      3. NIC Modes
      4. 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)
        2. This mode is applicable for the HCF only.

           

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

    This mode is applicable for the HCF only.

     

      1. Card Swap
      2. This feature is applicable for the HCF only.

         

      3. 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++
      2. 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.

         

      3. Reset
      4. 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.

         

      5. Memory use
      6. 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.

         

      7. Notify Control
      8. This feature is applicable for the HCF only.

         

      9. Download
      10. This feature is applicable for the HCF only.

         

      11. msf_assert
      12. This feature is applicable for the HCF only.

         

      13. Blocking
      14. This feature is applicable for the HCF only.

         

      15. MSF_COMPONENT_…. and DUI_COMPAT_……
      16. This feature is applicable for the HCF only.

         

      17. Exclusions
      18. Applicable for the HCF only.

         

      19. User scenarios
      20. Refer to DN

         

      21. 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
    2. 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
      2. 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

     

      1. 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
    2. HCF-light does not define any LTV-records additional to the Hermes.

       

    3. Appendix C - Hermes - HCF Record Correlation
    4. 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
    2. 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
      2. 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
        2. 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

           

        3. cnfOwnMACAddress
        4. 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.

           

        5. cnfDesiredSSID
        6. 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

           

           

        7. cnfOwnChannel
        8. 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)

           

        9. cnfOwnSSID
        10. 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 !!"

           

        11. cnfOwnATIMWindow
        12. To be added after stabilization of the firmware implementation

           

        13. cnfSystemScale
        14. 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).

           

        15. cnfMaxDataLength
        16. 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

           

           

        17. cnfWDSAddress
        18. This feature is applicable for the HCF only.

           

           

        19. cnfPMEnabled
        20. To be added after stabilization of the firmware implementation

           

        21. cnfPMEPS
        22. To be added after stabilization of the firmware implementation

           

           

        23. cnfMulticastReceive
        24. 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.

           

           

        25. cnfMaxSleepDuration
        26. 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

           

        27. cnfPMHoldoverDuration
        28. To be added after stabilization of the firmware implementation

           

        29. cnfOwnName
        30. 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.

           

        31. cnfOwnDTIMPeriod
        32. 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

           

        33. CnfWDSAddress1..6
        34. This feature is applicable for the HCF only.

           

        35. 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
      4. 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
        2. 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

           

           

        3. CreateIBSS
        4. 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

           

           

        5. FragmentationThreshold
        6. 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

           

           

        7. RTSThreshold
        8. 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

           

           

        9. TxRateControl
        10. 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

           

        11. 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

       

       

    3. 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
    2. 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.

      1. 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.

     

      1. 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.

     

      1. 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.

     

      1. 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

      1. 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.

     

      1. 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.

     

      1. 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.

      1. 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.

     

      1. RESEND FUNCTION ( hcf_resend )
      2. The Resend Function is applicable for the HCF only.

         

      3. Put Header FUNCTION (hcf_put_header )
      4. 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).
      1. SEND DIAGNOSTIC MESSAGE FUNCTION
        ( hcf_send_diag_msg )
      2. This function is supported by the HCF only

         

      3. 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.

     

      1. 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.

    *