TABLE OF CONTENTS

1. OpenSM/LID Matrix
2. OpenSM: LID Matrix/osm_lid_matrix_t
3. OpenSM: LID Matrix/OSM_LID_MATRIX_NO_PATH
4. OpenSM: LID Matrix/osm_lid_matrix_construct
5. OpenSM: LID Matrix/osm_lid_matrix_destroy
6. OpenSM: LID Matrix/osm_lid_matrix_init
7. OpenSM: LID Matrix/osm_lid_matrix_get
8. OpenSM: LID Matrix/osm_lid_matrix_get_max_lid_ho
9. OpenSM: LID Matrix/osm_lid_matrix_get_num_ports
10. OpenSM: LID Matrix/osm_lid_matrix_get_least_hops
11. OpenSM: LID Matrix/osm_lid_matrix_set
12. OpenSM: LID Matrix/osm_lid_matrix_set_min_lid_size

OpenSM/LID Matrix

    LID Matrix

    The LID Matrix object encapsulates the information needed by the
    OpenSM to manage fabric routes.  It is a two dimensional array
    index by LID value and Port Number.  Each element contains the
    number of hops from that Port Number to the LID.
    Every Switch object contains a LID Matrix.

    The LID Matrix is not thread safe, thus callers must provide
    serialization.

    This object should be treated as opaque and should be
    manipulated only through the provided functions.

    Steve King, Intel

OpenSM: LID Matrix/osm_lid_matrix_t

    osm_lid_matrix_t

    The LID Matrix object encapsulates the information needed by the
    OpenSM to manage fabric routes.  It is a two dimensional array
    index by LID value and Port Number.  Each element contains the
    number of hops from that Port Number to the LID.
    Every Switch object contains a LID Matrix.

    The LID Matrix is not thread safe, thus callers must provide
    serialization.

    Port 0 in the matrix serves a special purpose, in that it
    contains the shortest hop path for that LID through any port.

    This object should be treated as opaque and should be
    manipulated only through the provided functions.

typedef struct _osm_lid_matrix_t
{
    cl_vector_t         lid_vec;
    uint8_t             num_ports;

} osm_lid_matrix_t;

    lid_vec
        Vector (indexed by LID) of port arrays (indexed by port number)

    num_ports
        Number of ports at each entry in the LID vector.

OpenSM: LID Matrix/OSM_LID_MATRIX_NO_PATH

    OSM_LID_MATRIX_NO_PATH

    Value indicating there is no path to the given LID.
    This value must be larger than the largest legitimate
    number of hops in the subnet.

#define OSM_NO_PATH         0xFF

OpenSM: LID Matrix/osm_lid_matrix_construct

    osm_lid_matrix_construct

    This function constructs a LID Matrix object.

 void
osm_lid_matrix_construct(
    IN osm_lid_matrix_t* const p_lmx );

    p_lmx
        [in] Pointer to a LID Matrix object to construct.

    This function does not return a value.

    Allows calling osm_lid_matrix_init, osm_lid_matrix_destroy

    Calling osm_lid_matrix_construct is a prerequisite to calling any other
    method except osm_lid_matrix_init.

    LID Matrix object, osm_lid_matrix_init, osm_lid_matrix_destroy

OpenSM: LID Matrix/osm_lid_matrix_destroy

    osm_lid_matrix_destroy

    The osm_lid_matrix_destroy function destroys a node, releasing
    all resources.

void osm_lid_matrix_destroy(
    IN osm_lid_matrix_t* const p_lmx );

    p_lmx
        [in] Pointer to a LID Matrix object to destroy.

    This function does not return a value.

    Performs any necessary cleanup of the specified LID Matrix object.
    Further operations should not be attempted on the destroyed object.
    This function should only be called after a call to osm_lid_matrix_construct or
    osm_lid_matrix_init.

    LID Matrix object, osm_lid_matrix_construct, osm_lid_matrix_init

OpenSM: LID Matrix/osm_lid_matrix_init

    osm_lid_matrix_init

    Initializes a LID Matrix object for use.

ib_api_status_t
osm_lid_matrix_init(
    IN osm_lid_matrix_t* const p_lmx,
    IN const uint8_t num_ports );

    p_lmx
        [in] Pointer to an osm_lid_matrix_t object to initialize.

    num_ports
        [in] Number of ports at each LID index.  This value is fixed
        at initialization time.

    IB_SUCCESS on success

OpenSM: LID Matrix/osm_lid_matrix_get

    osm_lid_matrix_get

    Returns the hop count at the specified LID/Port intersection.

 uint8_t
osm_lid_matrix_get(
    IN const osm_lid_matrix_t* const p_lmx,
    IN const uint16_t lid_ho,
    IN const uint8_t port_num );

    p_lmx
        [in] Pointer to an osm_lid_matrix_t object.

    lid_ho
        [in] LID value (host order) for which to return the hop count

    port_num
        [in] Port number in the switch

    Returns the hop count at the specified LID/Port intersection.

OpenSM: LID Matrix/osm_lid_matrix_get_max_lid_ho

    osm_lid_matrix_get_max_lid_ho

    Returns the maximum LID (host order) value contained
    in the matrix.

 uint8_t
osm_lid_matrix_get_max_lid_ho(
    IN const osm_lid_matrix_t* const p_lmx );

    p_lmx
        [in] Pointer to an osm_lid_matrix_t object.

    Returns the maximum LID (host order) value contained
    in the matrix.

OpenSM: LID Matrix/osm_lid_matrix_get_num_ports

    osm_lid_matrix_get_num_ports

    Returns the number of ports in this lid matrix.

 uint8_t
osm_lid_matrix_get_num_ports(
    IN const osm_lid_matrix_t* const p_lmx );

    p_lmx
        [in] Pointer to an osm_lid_matrix_t object.

    Returns the number of ports in this lid matrix.

OpenSM: LID Matrix/osm_lid_matrix_get_least_hops

    osm_lid_matrix_get_least_hops

    Returns the number of ports in this lid matrix.

 uint8_t
osm_lid_matrix_get_least_hops(
    IN const osm_lid_matrix_t* const p_lmx,
    IN const uint16_t lid_ho );

    p_lmx
        [in] Pointer to an osm_lid_matrix_t object.

    lid_ho
        [in] LID (host order) for which to retrieve the shortest hop count.

    Returns the number of ports in this lid matrix.

OpenSM: LID Matrix/osm_lid_matrix_set

    osm_lid_matrix_set

    Sets the hop count at the specified LID/Port intersection.

cl_status_t
osm_lid_matrix_set(
    IN osm_lid_matrix_t* const p_lmx,
    IN const uint16_t lid_ho,
    IN const uint8_t port_num,
    IN const uint8_t val );

    p_lmx
        [in] Pointer to an osm_lid_matrix_t object.

    lid_ho
        [in] LID value (host order) to index into the vector.

    port_num
        [in] port number index into the vector entry.

    val
        [in] value (number of hops) to assign to this entry.

    Returns the hop count at the specified LID/Port intersection.

OpenSM: LID Matrix/osm_lid_matrix_set_min_lid_size

    osm_lid_matrix_set_min_lid_size

    Sets the size of the matrix to at least accomodate the
    specified LID value (host ordered)

 cl_status_t
osm_lid_matrix_set_min_lid_size(
    IN osm_lid_matrix_t* const p_lmx,
    IN const uint16_t lid_ho );

    p_lmx
        [in] Pointer to an osm_lid_matrix_t object.

    lid_ho
        [in] Minimum LID value (host order) to accomodate.

    Sets the size of the matrix to at least accomodate the
    specified LID value (host ordered)