    
    
    Configuring HAM driver failover using the CFG.NLM utility
    =========================================================

    This document describes how to use CFG.NLM to configure ham 
    driver failover (as an alternate solution to the SanSurfer 
    failover configuration software).  For more information, 
    see "Creating the QL2x00.CFG configuration file" below.  
    
    Please do read this document entirely before attempting to 
    proceed to use CFG.NLM to configure ham driver failover.


    File path and name (this file must reside at this path): 
    
        C:\NWSERVER\QL2x00.CFG


    File Format (version 4):
    
        configVersion
        adapterCount
        adapterNodeName[i]
            deviceCount
            deviceNodeName[j]
                devicePrimaryPortName
                portMask
                pathMask
                lunMask
                deviceMask


    Notes on File Format: 
        
        a. Indentation is used to indicate levels of hierarchy grouping;
           each indentation level is subordinate to the level above it.

        b. [i] indicates the field and its subordinate group iterates
           (the field and its group of subordinates repeats i times).
           
        c. Subordinate groups can be nested (i.e. multiple levels).

        d. All fields are hexadecimal numbers. 


    Example File Format (indented to match "File format" above):
    
        4
        2
        210000E08B011C8C
            3
            2000020370099DE9
                2100020370099DE9
                00000000
                FF000000
                00000000
                0         
            2000020370091370
                2100020370091370
                FF000000
                00000000
                00000000
                0
            2000020370093422
                2200020370093422
                00000000
                FF000000
                00000000
                0
        210000E08B017539
            3
            2000020370099DE9
                2200020370099DE9
                00000000
                FF000000
                00000000
                0         
            2000020370091370
                2200020370091370
                FF000000
                FF000000
                00000000
                0
            2000020370093422
                2100020370093422
                00000000
                00000000
                00000000
                0
    
    
    Additional Notes on File Format: 
        
        a.  The configVersion is as follows:

                0 for ham versions 5.50u or earlier and any 5.40.

                2 for ham versions 6.50d or earlier down to 5.50v.

                4 for ham versions 6.50e and later.


        b.  The adapterNodeName[i] block repeats for each adapter,
            upto adapterCount number of times:
        
                adapterNodeName[i]
                    deviceCount
                    deviceNodeName[j]
                        devicePrimaryPortName
                        portMask
                        pathMask
                        lunMask
                        deviceMask

        
        c.  The deviceNodeName[j] block repeats for each device,
            upto deviceCount number of times, for each adapter:
    
                deviceNodeName[j]
                    devicePrimaryPortName
                    portMask 
                    pathMask
                    lunMask
                    deviceMask


        d.  Adapter and device nodenames may not contain whitespace.

        
        e.  Indentation whitespace contained in the file is ignored.
        

    
    Description of fields in File Format:

    
        adapterNodeName:
        
            Specifies (identifies) a particular adapter as the point 
            of reference for all devices associated with this adapter.
            
            Also referred to as the specified adapter.
            
    
        deviceNodeName:
        
            Identifies a particular device.
            
            Each device is a single node and has multiple ports.
            
            Each device port is identified with a portname.
            
            Each device has a single nodename and multiple portnames.
            
            Also referred to as the specified device.
    
    
        devicePrimaryPortName:
        
            Specifies (identifies) a particular device port as the point 
            of reference for all luns associated with this device.
            
            Also referred to as the specified port.
    
            
        portMask  (version 4):
        
            Configures each lun to be either on the specified device 
            port or on the other device port.
            
            See How To Specify Luns below.
           
    
        pathMask:
        
            Configures each lun to be either on the specified adapter 
            or on the other adapter.
            
            See How To Specify Luns below.
           
        
        lunMask:
        
            Configures each lun to be either enabled or disabled.  
        
            A disabled lun is ignored until enabled.
        
            See How To Specify Luns below.
           
        
        deviceMask:
        
            Configures the current device to be either enabled or disabled.
        
            Single bit, 0 for enabled, 1 for disabled (masked).
        
            Disabled device (and all its luns) will be ignored until enabled.


    Specifying Luns:
    
        The mask fields are: portMask, pathMask, lunMask.

        The mask fields each have identical form, and each identify 
        luns in identical manner, but their functions are different 
        (see "Description of fields in File Format" above).
        
        
        Each mask field has the following form:

            A string of bytes ordered from left to right starting at byte 0. 
        
            The bits in each byte are ordered from right to left as 0 to 7. 
    
            The absolute bit position n in the string is the lun number
            (lun n), and is calculated as follows:
            
                n = byte * 8 + bit  
            
            where:
             
                bit  = relative bit position in a byte (0 thru 7)
                byte = absolute byte index (starting at 0)


        The function of each mask field is as follows:

            For portMask:
            
                At absolute bit position n (lun n):
                
                    0 puts lun n on the specified port,
                    1 puts lun n on the other port.
               
            For pathMask:
        
                At absolute bit position n (lun n):
                
                    0 puts lun n on the specified adapter,
                    1 puts lun n on the other adapter.
               
            For lunMask:
                 
                 At absolute bit position n (lun n):
                 
                    0 enables lun n,
                    1 disables lun n.

                
        Notes on Specifying Luns:
        
            In version 2, theportMask field does not exist, and so the 
            portMask is assumed to be identical to the pathMask; this 
            means that luns on the specified adapter use the specified 
            port on the specified device.
            
            In version 4, the portMask and pathMask are mutually 
            independent; this allows finer path/port granularity.
            
   
        Examples on Specifying Luns:
         
            Each mask below can be either a portMask or a pathMask;
            port/adapter as used below has the following contexts:
           
                For a portMask, the context is port.
                For a pathMask, the context is adapter.
                
                
            (Remember that every pair of ascii digits is a single byte).
            
            
            0100000000000000....    Lun 0 is on other port/adapter.
                                    All others are specified port/adapter.
            
            FE00000000000000....    Luns 1..255 are on other port/adapter.
                                    Lun 0 is on specified port/adapter.
            
            FFFF000000000000....    Luns 0..15 are on other port/adapter.
                                    All others are on specified port/adapter.
            
            0101010100000000....    Luns 0, 8, 16, 24 are on other port/adapter.
                                    All others are on specified port/adapter.
            
            8001000000000000....    Luns 7 and 8 are on other port/adapter.
                                    All others are on primary port/path.
                                  
            AAAAAAAAAAAAAAAA....    Odd luns are on other port/adapter.
                                    All others are on specified port/adapter.
                                  
            5555555555555555....    Even luns are on other port/adapter.
                                    All others are on specified port/adapter.
                                  

    Terminology regarding Path/Port:
    
        The following terms usually have the following meanings:
        
            Driver means HAM driver.
            
            Path usually means adapter path.
            Port usually means target port.
        
        A path physically connects a fabric switch and an adapter.
        A port physically connects a fabric switch and a storage target.
        
        Path failover may occur independently of port failover.
        Port failover may occur independently of path failover.


    Creating the QL2x00.CFG configuration file:
    
        If the configuration file does not exist, then all devices 
        and luns on all adapters are enabled; all new adapters and
        devices are enabled.
    
        If the configuration file exists, then only the devices and
        adapters mentioned in the file are configured; all others
        are not configured (disabled), and any new adapters/devices 
        are ignored (disabled).
    
        If the configuration file contains zero for the adapterCount, 
        then no adapters/devices are configured, and all new ones are 
        ignored (disabled).
    
        When adding new adapters or devices, you may want to delete
        the configuration file (from DOS prompt do DEL QL2x00.CFG) 
        and create a new one (after the driver has loaded, from NW 
        server prompt do CFG /FS).  Or if you know the adapter/device
        nodenames, you may edit the configuration file (from NW5 do 
        EDIT C:QL2x00.CFG).  Or you may delete all lines except the 
        first (a single line containing "4") from the configuration 
        file, and create a new configuration file after the driver 
        has loaded (CFG /FS).
    
        If you have multiple adapters and/or target ports to the same 
        device), you may select one of these to be currently active 
        (primary) as follows:
    
            First, from the server console prompt, do CFG /SF or 
            CFG /SL to view all nodenames and portnames.
            
            Second, edit the configuration file to change the 
            the pathMask, portMask and primaryPortName for the 
            current device (on the current adapter); usually, 
            the portnames on a multiport device differ by one 
            or two bits, and look almost identical to the 
            nodename (wwn).
            
            Third, load the new configuration file (CFG /FL), 
            or unload and reload the ham driver.
            
        After failover, if the cause is fixed, then failback 
        is automatic after 15 seconds; you may force failback 
        before this by reloading the configuration file 
        (from NW server prompt do CFG /FL).
    
        You may view the current configuration to see the 
        port id that each configured device is using (from 
        the NW server prompt do CFG /P).  

        CFG.NLM ignores indentation whitespace contained in the file.
        
        The ham driver supports the following:
        
           Adapter path failover per lun (multiple adapter paths).
           Target port failover per lun (multiple target ports).
           

    =====================================================================
    
