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

       

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

         

      2. HCF versus HCF-light

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

    • DUI, DUIF, Utility I/F, UIL, Diagnostic Message

    • assert

    • Download

    • Notify

    • Mailbox

    • Configuration Table

    • Configuration Management, Actor Range, Supplier Range

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

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

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

     

      1. Network Operating Systems Environment

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

     

     

    1. Interfaces

      1. Syntax conventions

    Parameter sequence:

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

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

    Parameter type of parameters of a "numerical nature":

    • If the parameter or return status is inherently 8, 16, or 32 bits, due to its relationship with the hardware aspects of the NIC, its type is hcf_8, hcf_16, or hcf_32, respectively. Hcf_8, hcf_16, and hcf_32 are unsigned quantities of 8, 16, and 32 bits, respectively. They are defined in the configuration process in HCFCFG.H (see section 4.2.2)

    • If the maximum value of a parameter is in the range 0x8000 through 0xFFFF (32786 through 65535), its type is unsigned int.

    • If the maximum value of a parameter equals or exceeds 0x10000 (65536), its type is hcf_32.

    • If the parameter represents a "command", an enumerated type is used to allow C++ type checking.

    • If none of the above applies, the standard type int is used, regardless whether negative values make sense for the parameter.
      By expressing parameters in this "most natural" size for the platform the code must run on, the code generated by the compiler will be optimized (e.g. the use of a 16-bit word in 32-bits mode on an 80x86 results in an override prefix for each machine instruction using that word.)
      By using the signed rather than the unsigned int, it is expected that the chance of introducing bugs as result of unexpected C-promotion rules is the smallest.

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

      2. Code Adaptation Controls

        1. System Constants

          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

         

      4. Information Transfer

        1. I/F Block Concept

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

    The IFB consists of the following parts:

    • a part used by the HCF to pass values to the MSF. The MSF has read only access here.

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

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

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

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

     

        1. LTV Record Concept

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

    • a Length field, specifying the combined size of the Type and Data field

    • a Type field, identifying how the data in the Data field is to be interpreted

    • a Data field, the remainder of the LTV Record, carrying the actual data

        1. Hermes Record Concept

          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.

           

        2. Configuration Table concept

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

           

        3. MailBox Concept

          4. The MailBox concept is applicable for the HCF only.

           

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

           

        2. Receive and Transmit Frame Structures

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

    • Control fields for the WMAC Controller

    • Header information

    • Data

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

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

    The following figure shows the formats of these three segments:

    Byte offset

    HCF Mnemonic

    Transmit Frame Structure

    Structure

    segment

    Receive Frame Structure

    		  

    00

    -2E

    HFS_STAT

    Status

    Control

    Status

    		  

    02

    -2C

    		  

    0

    Fields

    		    
         

    0

    Common for

    		    

    06

    -28

    HFS_Q_INFO

    SwSupport

    802.11

    Signal / Silence

    		  
           

    and

    Rate

    		  

    0A

    -24

    		  

    0

    802.3

    		    

    0C

    -22

    HFS_TX_CNTL

    TxControl

    		      

    0E

    -20

    HFS_FRAME_CNTL

    FrameControl

    Header Info

    FrameControl

    		  

    10

    -1E

    HFS_ID

    Duration/ID

    		  

    Duration/ID

    		  

    12

    00

    HFS_ADDR_1

    Address1

    802.11

    Address1

    		  
           

    Format

    		   
                 

    18

    06

    HFS_ADDR_2

    Address2

    		  

    Address2

    		  
                 
                 

    1E

    0C

    HFS_ADDR_3

    Address3

    		  

    Address3

    		  
                 
                 

    24

    12

    HFS_SEQ_CNTL

    SequenceControl

    		  

    SequenceControl

    		  

    26

    14

    HFS_ADDR_4

    Address4

    		  

    Address4

    		  
                 
                 

    2C

    1A

    HFS_DAT_LEN

    DataLen (Little Endian)

    		  

    DataLen (Little Endian)

    		  

    2E

    00

    HFS_ADDR_DEST

    DestAddr

    Header Info

    DestAddr

    		  
                 
           

    802.3

    		    

    34

    06

    HFS_ADDR_SRC

    SrcAddr

    Format

    SrcAddr

    		  
                 
                 

    3A

    0C

    HFS_LEN

    Length (Big Endian)

    		  

    Length (Big Endian)

    (ref Table 4)

    3C

    0E

    HFS_DAT

    Data /

    SNAP header

    Data Info

    Data /

    SNAP header

    		  

    3E

    		    

    Data /

    SNAP header

    		  

    Data /

    SNAP header

    		  

    40

    		    

    Data /

    SNAP header

    		  

    Data /

    SNAP header

    		  

    42

    		  

    HFS_TYPE

    Data /

    E-II Type

    		  

    Data /

    E-II Type

    (ref Table 4)
         

    Data

    Common for

    Data

    		  
           

    802.11

    		    
           

    and

    		   
           

    802.3

    		    
                 
         

    (Max. 2304 bytes)

    		  

    (Max. 2304 bytes)

    		  

    Figure 1 Frame structures formats

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

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

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

    HCF-light only supports the 802.3_pure mode.

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

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

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

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

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

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

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

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

    Note the exceptional handling of the HFS_LEN field.

    • In case of 802.3 access of this field yields the length value (absolute offset 0x003A).

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

     

    Offset parameter

    rel.offset

    Frame type

    Abs.offset

    HFS_ADDR_1

    0x0000

    802.11

    0x0012

    HFS_ADDR_DEST

    0x0000

    802.3

    0x002E

    HFS_ADDR_DEST

    0x0000

    encapsulated

    0x002E

    HFS_DAT_LEN

    0x001A

    802.11

    0x002C

    HFS_DAT_LEN + 2

    0x001C

    802.11

    0x003C

    HFS_DAT_LEN

    N/A.

    802.3

    N/A.

    HFS_DAT_LEN

    N/A.

    encapsulated

    N/A.

    HFS_DAT

    0x000E

    802.11

    0x003C

    HFS_DAT

    0x000E

    802.3

    0x003C

    HFS_DAT

    0x000E

    encapsulated

    0x0044

    HFS_LEN

    0x000C

    802.3

    0x003A

    HFS_LEN

    0x000C

    encapsulated

    0x0042

    HFS_TYPE (note 1)

    N/A.

    N/A.

    N/A.

    HFS_Q_INFO

    -0x0028

    any Rx Frame

    0x0006

    Note 1: To access the type field of an encapsulated frame, the mnemonic HFS_DAT must be used.

    Note 2: For HCF-light only the 802.3 Frame type entries are applicable

    Table 4 Correlation frame type, hcf_get_data offset parameter and offsets

      2. Data structures and Input/Output Customization

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

    • the type of I/O space (port I/O versus memory mapped I/O)

    • odd and even byte addressing of NIC RAM

    • the Endianess of the platform

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

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

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

    The NIC has a Little Endian (LE) architecture.

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

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

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

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

     

        1. Transmit/Receive Frames

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

           

        2. LTV-records

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

    • the L- and T-field have "native" Endianess as seen from the Host

    • the V-field is Little Endian

    As a consequence:

    • the HCF as well as the MSF can manipulate L and T in a natural way, e.g. use L as a loopcounter, do range checking on T values.

    • when passing the L- and T-field from NIC and the Host or vice versa, the HCF must adjust the Endianess, which is automatically done when using the IN_/OUT_PORT_WORD macros

    • when passing the V-field to/from the Host, the HCF is not sensitive for the Endianess, which is automatically done when using the IN_/OUT_PORT_STRING macros

    • when creating/interpreting the V-field, an BE MSF must be aware of the deviating Endianess.

     

        1. IN_PORT_WORD(port)

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

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

    • the Length and Type field of all Configuration Records

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

    For internal purposes, the HCF uses IN_PORT_WORD to access

    • the Value part of a some Configuration Records, e.g. cnfOwnATIMWindow (FC05)

    • the Value part of Information Frame Structure, e.g. Communication Tallies (F100)

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

     

        1. OUT_PORT_WORD(port, value)

          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.

           

        2. Void IN_PORT_STRING( port, dest, len)

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

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

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

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

    • the Address sub-fields of 802.11 Header of the Receive Frame Structure

    • the complete 802.3 Header of the Receive Frame Structure

    • the DataInfo part of the Receive Frame Structure

     

        1. void OUT_PORT_STRING( port, src, len)

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

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

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

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

     

        1. common notes for IN_PORT_STRING and OUT_PORT_STRING

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

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

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

    Other environments may have other constraints

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

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

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

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

    Prototype

    Description

    hcf_8 IN_PORT_BYTE( hcf_io port )

    Reads a byte (8 bits) from the specified port.

    hcf_16 IN_PORT_WORD( hcf_io port )

    Reads a Little Endian word (16 bits) from the specified port and converts it to Native Endian format.

    void OUT_PORT_BYTE( hcf_io port,
    hcf_8 value )

    Writes a byte (8 bits) to the specified port.

    void OUT_PORT_WORD( hcf_io port,
    hcf_16 value)

    Writes a Little Endian word (16 bits) to the specified port after converting it from Native Endian format.

    void IN_PORT_STRING( hcf_io port,
    hcf_8 FAR *dest,
    int len )

    Reads len number of words from the specified port to the (FAR) byte address dest in PC-RAM without conversion of the Endianess.

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

    void OUT_PORT_STRING( hcf_io port,
    hcf_8 FAR *src,
    int len )

    Writes len number of words from the (FAR) byte address src in PC-RAM to the specified port without conversion of the Endianess.

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

    Table 5 Macros for optimization of string I/O

    2. functional descriptions

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

         

      2. NIC Configuration Group

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

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

    • Enable function

    • Download (see the Configuration functions)

    • Diagnose (see the Action functions)

    Enable Function

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

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

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

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

     

    Disable Function

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

    .

    Action Function

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

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

    Configuration Functions

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

     

      1. Data Transfer Group

        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.

         

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

      2. Polled control

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

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

         

      3. Interference control

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

    • hcf_put_data

    • hcf_send

    • hcf_get_info

    • hcf_put_info

    • hcf_send_diag_msg (not available in HCF-light),

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

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

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

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

     

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

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

     

      1. Connect/Disconnect control

        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.

         

      2. Transmission control

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

    • the protocol stack (the "normal" source for drivers)

    • the Driver/Utility I/F (ref. 5) (not available in HCF-light)

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

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

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

     

      1. NIC Configuration

        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.

         

      2. NIC Modes

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