Mellanox Technologies

*******************************************************************************
***                  guid2mac_checker User's Guide                          ***
***                                                                         ***
***            Document #3052 ; Rev 1.0 ; January 29, 2009                  ***
*******************************************************************************


Contents
========
1. Scope
2. Usage


1. Scope
========
When generating a MAC for an IPoIB interface, one of the following scenarios is
true:
1. The IPoIB driver recognizes the HCA port’s GUID
2. The IPoIB driver does not recognize the GUID but a GUID mask exists
3. The IPoIB driver neither recognizes the GUID nor does a GUID mask exist 

The following paragraphs describe how each scenario is dealt with.

1. When an IPoIB interface is created, the IPoIB driver first checks the HCA
   port’s GUID. In case it recognizes the GUID, the driver creates a
   corresponding MAC based on this GUID according to a mapping embedded in the
   driver code.

2. In case the driver does not recognize the GUID, it attempts to assign a MAC
   by means of a GUID mask. Specifically, the IPoIB driver will check the data
   of the registry value ‘GUIDMask’, which is located in the interface registry
   key (located under HKLM\System\CurrentControlSet\Control\Class\{4D36E972-E325-11CE-BFC1-08002bE10318}).
   If the 8-bit data contains exactly 6 non-zero bits, then a MAC will be
   generated for the IPoIB interface by applying the data as a mask to the HCA
   port’s GUID. The result of applying the mask is a 6-byte MAC.

   Example of MAC generation using a valid mask:
      mask = 0xe7 = 11100111 (binary);
      Port GUID = 0002c90200112233
      => MAC = 0002c9112233
     where a (binary) 1 in the mask indicates to keep the corresponding GUID
     byte, and a (binary) 0 indicates to eliminate the corresponding GUID byte.

3. In case the driver neither recognizes the GUID nor finds a valid mask (i.e.,
   the mask contains less or more than 6 non-zero bits), then the driver
   assigns a locally administrated MAC (with 02-00-00-00-00-01 being the first
   to be assigned).
   Note, however, that the DHCP server may not assign an IP address for an
   IPoIB interface with a locally administrated MAC.

   To fix this problem, it is possible to use the guid2mac_checker utility to
   find or allocate a mask. If guid2mac_checker recognizes the GUID, then it 
   creates the registry value ‘GUIDMask’ with the GUID’s associated mask. After
   this, the user needs to disable and re-enable the IPoIB interface for the
   IPoIB driver to locate the added mask (as in case 2 above).

   In case the guid2mac_checker script does not recognize the GUID, then (a) if
   the script is running interactively, it will ask the user to suggest a mask
   or offer the default 0xe7 mask; or (b) if the utility is running 
   non-interactively, then it will use the default 0xe7 mask. Next, 
   guid2mac_checker will create the registry value ‘GUIDMask’ with the GUID’s
   associated mask. After this, the user needs to disable and re-enable the
   IPoIB interface for the IPoIB driver to locate the added mask (as in case 2
   above).


2. Syntax
=========
guid2mac_checker.exe [-h] [-f] [-s] [-d <mask>]

Options:

-h            Print this help message and exit.

-f            This is a fix operation. (Default operation is: check)

-s            Silent mode. (Default mode is: interactive)

-d <mask>     Change the GUID mask used in silent mode. (Default mask is: 0xe7)