/****************************************************************************
*****************************************************************************
**
** File Name
** ---------
**
** BU.H
**
*****************************************************************************
*****************************************************************************
**
** Description
** -----------
**
** Bit Utilities Component Public Interfaces Header File
**
** This source file defines the public interfaces to the bit utilities
** component.  This component contains a collection of services that provide
** encapsulation of low level bit masking and setting operations.  Among
** the services provided are a set for converting from bit number (0..15)
** to a bit setting mask or a bit clearing mask.  A service for byte swapping
** 16-bit words is also provided.
**
*****************************************************************************
*****************************************************************************
**
** Source Change Indices
** ---------------------
**
** Porting: <none>0----<major>         Customization: <none>--2--<major>
**
**    *  Application developers may wish to provide processor specific
**       performance enhanced versions of some of the BU services.
**
*****************************************************************************
*****************************************************************************
**
** Services List
** -------------
**
** Bit Mask Conversions:
**
**    BU_BitNumToMask()       Change bit number to bit setting mask
**    BU_BitNumToNotMask()    Change bit number to bit clearing mask
**
**
** Byte Manipulation Services
**
**    BU_HiByte()             Extract the high byte of a word
**    BU_HiWord()             Extract the high word of a longword
**    BU_LoByte()             Extract the low byte of a word
**    BU_LoWord()             Extract the low word of a longword
**    BU_SwapBytes()          Swap bytes in a word
**
**
** Shift Services
**
**    BU_ShiftLeft()          Shift an integer left once
**    BU_ShiftLeftMultiple()  Shift an integer left multiple times
**
**
** Bit Array Services
**
**    BU_ClearBit()           Clear one bit of a bit array
**    BU_GetBit()             Get one bit of a bit array
**    BU_SetBit()             Set one bit of a bit array
**    BU_ClearBitArray()      Clear all bits of a bit array
**    BU_BitArrayAllZero()    Test if all bits in a bit array are zero
**
*****************************************************************************
*****************************************************************************
**                                                                         **
** ETHERNET/IP EXAMPLE CODE                                                **
** COPYRIGHT (c) 2000-2005 ODVA (Open DeviceNet Vendor Association)		   **
**						   & ControlNet International Ltd.                 **
**                                                                         **
** All rights reserved, except as specifically licensed in writing.        **
** Use of the Ethernet/IP Example Protocol Software is subject to          **
** ODVA's and ControlNet International's Terms of Use Agreement.           **
** The following work constitutes example program code and is intended     **
** merely to illustrate useful programming techniques.  The user is        **
** responsible for applying the code correctly.  The code is provided      **
** AS IS without warranty and is in no way guaranteed to be error-free.    **
**                                                                         **
*****************************************************************************
*****************************************************************************
*/

/****************************************************************************
*****************************************************************************
**
** Change Log
** ----------
**
**
*****************************************************************************
*****************************************************************************
*/

#ifndef BU_H
#define BU_H



/****************************************************************************
**
** Globals
**
*****************************************************************************
*/

/*---------------------------------------------------------------------------
**
** BU_BitTbl
** BU_NotBitTbl
**
**---------------------------------------------------------------------------
**
** The two tables below are used to rapidly translate from bit numbers to bit
** masks.  A lookup through "BitTbl" would, for instance, be used to change
** 0x03 to 00001000 binary and a corresponding lookup through "NotBitTbl"
** would be used to change 0x03 to 11110111 (inverted mask). These tables are
** usable up to a range of 16 bits (width).
**
**---------------------------------------------------------------------------
*/

extern UINT16 const BU_aiBitTbl[];
extern UINT16 const BU_aiNotBitTbl[];



/****************************************************************************
**
** Services
**
*****************************************************************************
*/

/*---------------------------------------------------------------------------
**
** BU_BitNumToMask()
**
** Convert an unsigned bit number (an index) into a bit setting mask.
**
**---------------------------------------------------------------------------
**
** Inputs:
**    iX                      - the original index in the range 0x00 .. 0x0f
**
** Outputs:
**    Returns                 - corresponding bit mask with one bit set
**
** Usage:
**    iOut = BU_BitNumToMask( iX )
**
**---------------------------------------------------------------------------
*/

#define BU_BitNumToMask( iX )  BU_aiBitTbl[ iX ]



/*---------------------------------------------------------------------------
**
** BU_BitNumToNotMask()
**
** Convert an unsigned bit number (an index) into a bit clearing mask.
**
**---------------------------------------------------------------------------
**
** Inputs:
**    iX                      - the original index in the range 0x00 .. 0x0f
**
** Outputs:
**    Returns                 - corresponding bit mask with one bit clear
**
** Usage:
**    iOut = BU_BitNumToNotMask( iX )
**
**---------------------------------------------------------------------------
*/

#define BU_BitNumToNotMask( iX )  BU_aiNotBitTbl[ iX ]



/*---------------------------------------------------------------------------
**
** BU_ClearBit()
** BU_GetBit()
** BU_SetBit()
**
** Clear/get/set a bit in a multi byte bit array.
**
**---------------------------------------------------------------------------
**
** Inputs:
**    xName                   - Name of bit array
**    iBit                    - Which bit in the array
**
** Outputs:
**    Return                  - Get returns TRUE for 1 bit, FALSE for 0 bit.
**                              Set/Clear return nothing.
**
** Usage:
**    BU_ClearBit( abStartedConns, i );
**    if( BU_GetBit( abStartedConns, i ) )...
**    BU_SetBit( abStartedConns, i );
**
**---------------------------------------------------------------------------
*/

#define BU_ClearBit( xName, iBit ) \
   ((UINT8*)(xName))[ (iBit) >> 3 ] &= (UINT8)(BU_BitNumToNotMask( (iBit) & 0x07 ))

#define BU_GetBit( xName, iBit ) \
   ( ((UINT8*)(xName))[ (iBit) >> 3 ] & (UINT8)(BU_BitNumToMask( (iBit) & 0x07 )) )

#define BU_SetBit( xName, iBit ) \
   ((UINT8*)(xName))[ (iBit) >> 3 ] |= (UINT8)(BU_BitNumToMask( (iBit) & 0x07 ))



/*---------------------------------------------------------------------------
**
** BU_ClearBitArray()
**
** Clear all bits in a multi byte bit array.
**
**---------------------------------------------------------------------------
**
** Inputs:
**    xName                   - Name of bit array
**    iBits                   - Number of bits in the array
**
** Outputs:
**    None
**
** Usage:
**    BU_ClearBitArray( abStartedConns, 32 );
**
**---------------------------------------------------------------------------
*/

#define BU_ClearBitArray( xName, iBits ) \
   UC_SetMem( (void*)(xName), 0, (iBits) >> 3 )



/*---------------------------------------------------------------------------
**
** BU_BitArrayAllZero()
**
** Test for all bits equal 0 in a multi byte bit array.
**
**---------------------------------------------------------------------------
**
** Inputs:
**    xName                   - Name of bit array
**    iBits                   - Number of bits in the array
**
** Outputs:
**    Return                  - TRUE if all bits in array 0
**                              FALSE if any bit in array 1
**
** Usage:
**    if( BU_BitArrayAllZero( abStartedConns, 32 ) )...
**
**---------------------------------------------------------------------------
*/

#define BU_BitArrayAllZero( xName, iBits ) \
   ( UC_CompareMemToByte( (void*)(xName), 0, (iBits) >> 3 ) == NULL )



/*---------------------------------------------------------------------------
**
** BU_HiByte()
** BU_LoByte()
**
** Extract the most or least significant byte of a 16-bit word.
**
**---------------------------------------------------------------------------
**
** Inputs:
**    iX                      - a 16-bit word
**
** Outputs:
**    Returns                 - the most significant byte
**
** Usage:
**    bHi  = BU_HiByte( iX )
**    bLow = BU_LoByte( iX )
**
**---------------------------------------------------------------------------
*/

#define BU_HiByte( iX )  ( ( (iX) >> 8 ) & 0x00FF )
#define BU_LoByte( iX )  ( (iX) & 0x00FF )



/*---------------------------------------------------------------------------
**
** BU_HiWord()
** BU_LoWord()
**
** Extract the most or least significant word of a 32-bit word.
**
**---------------------------------------------------------------------------
**
** Inputs:
**    lX                      - a 32-bit word
**
** Outputs:
**    Returns                 - the most significant word
**
** Usage:
**    iHigh = BU_HiWord( lX )
**    iLow  = BU_LoWord( lX )
**
**---------------------------------------------------------------------------
*/

#define BU_HiWord( lX )  ( (UINT16)(  ( (lX) >> 16) & 0x0000FFFFL ) )
#define BU_LoWord( lX )  ( (UINT16)( (lX) & 0x0000FFFFL ) )



/*---------------------------------------------------------------------------
**
** BU_ShiftLeft()
**
** Shift an arbitrary length integer left exactly one time.
** This is used to avoid generating references to library functions for long
** integers.
**
**---------------------------------------------------------------------------
**
** Inputs:
**    nX                      - the original integer
**
** Outputs:
**    return                  - the shifted integer
**
** Usage:
**    BU_ShiftLeft( nX )
**
**---------------------------------------------------------------------------
*/

#define BU_ShiftLeft( nX )  (nX) += (nX)



/*---------------------------------------------------------------------------
**
** BU_ShiftLeftMultiple()
**
** Shifts an arbitrary length integer left a multiple number of times.
** This is used to avoid generating references to library functions
** for long integers.
**
**---------------------------------------------------------------------------
**
** Inputs:
**    nX                      - the original integer
**    iN                      - the shift count
**
** Outputs:
**    return                  - the shifted integer
**
** Usage:
**    BU_ShiftLeftMultiple( nX, iN )
**
**---------------------------------------------------------------------------
*/

#define BU_ShiftLeftMultiple( nX, iN )    \
   {                                      \
      UINT16 ixxx;                        \
      for( ixxx = (iN); ixxx; ixxx-- )    \
      {                                   \
         (nX) += (nX);                    \
      }                                   \
   }



/*---------------------------------------------------------------------------
**
** BU_SwapBytes()
**
** This service swaps the high and low bytes of a 16 bit integer.  The non-
** Intel version of this service presented below is portable, but can most
** likely be optimized for specific processors.
**
**---------------------------------------------------------------------------
**
** Inputs:
**    iX                      - the original integer
**
** Outputs:
**    (side-effect)           - the original integer with its bytes swapped
**
** Usage:
**    BU_SwapBytes(iX)
**
**---------------------------------------------------------------------------
*/

#ifdef INTEL80x86
#define BU_SwapBytes( iX ) \
   ASM{ mov ax,iX }  ASM{ xchg ah,al }  ASM{ mov iX, ax }
#else
#define BU_SwapBytes( iX )  \
   ( ( ( (iX) & 0xFF00 ) >> 8 ) | ( ( (iX) & 0x00FF ) << 8 ) )
#endif



#endif  /* inclusion lock */

/****************************************************************************
**
** End of BU.H
**
*****************************************************************************
*/