TABLE OF CONTENTS

1. OpenSM/P_Key Table
2. OpenSM: P_Key Table/osm_pkey_tbl_t
3. OpenSM: P_Key Table/osm_pkey_tbl_new
4. OpenSM/Physical Port
5. OpenSM: Physical Port/osm_physp_t
6. OpenSM: Physical Port/osm_physp_construct
7. OpenSM: Physical Port/osm_physp_init
8. OpenSM: Physical Port/osm_physp_is_valid
9. OpenSM: Physical Port/osm_physp_set_port_info
10. OpenSM: Physical Port/osm_physp_get_remote
11. OpenSM: Physical Port/osm_physp_get_port_guid
12. OpenSM: Physical Port/osm_physp_link
13. OpenSM: Physical Port/osm_physp_link_exists
14. OpenSM: Physical Port/osm_physp_has_any_link
15. OpenSM: Physical Port/osm_physp_get_port_num
16. OpenSM: Physical Port/osm_physp_get_port_info_ptr
17. OpenSM: Physical Port/osm_physp_get_node_ptr
18. OpenSM: Physical Port/osm_physp_get_port_state
19. OpenSM: Physical Port/osm_physp_get_base_lid
20. OpenSM: Physical Port/osm_physp_get_lmc
21. OpenSM: Physical Port/osm_physp_get_dr_path_ptr
22. OpenSM/Port
23. OpenSM: Port/osm_port_lid_category_t
24. OpenSM: Port/osm_port_t
25. OpenSM: Port/osm_port_construct
26. OpenSM: Port/osm_port_destroy
27. OpenSM: Port/osm_port_destroy
28. OpenSM: Port/osm_port_init
29. OpenSM: Port/osm_port_new
30. OpenSM: Port/osm_port_get_base_lid
31. OpenSM: Port/osm_port_get_lmc
32. OpenSM: Port/osm_port_get_guid
33. OpenSM: Port/osm_port_get_phys_ptr
34. OpenSM: Port/osm_port_get_parent_node
35. OpenSM: Physical Port/osm_physp_get_parent_node
36. OpenSM: Port/osm_port_categorize_lid
37. OpenSM: Port/osm_port_get_lid_range_ho
38. OpenSM: Port/osm_port_add_new_physp

OpenSM/P_Key Table

    P_Key Table Structure

    The P_Key Table Structure provides a simple table structure
    to group P_Key objects.  Calling code accesses this structure
    directly.

    Steve King, Intel

OpenSM: P_Key Table/osm_pkey_tbl_t

    osm_pkey_tbl_t

    Contains an array of P_Key objects.

typedef struct _osm_pkey_tbl
{
    uint32_t                size;
    ib_net16_t              tbl[1];

} osm_pkey_tbl_t;

    size
        The number of P_Key objects in the table.

    tbl
        Array of P_Key objects associated with this port.
        Index is contiguous from 0 to size - 1.
        MUST BE LAST MEMBER OF THE OBJECT!

    Port, P_Key object

OpenSM: P_Key Table/osm_pkey_tbl_new

    osm_pkey_tbl_new

    This function creates and initializes a P_Key Table object.

osm_pkey_tbl_t* osm_pkey_tbl_new(
    IN uint32_t const size );

    size
        [in] Number of entries in the P_Key Table.

    On success, returns a pointer to a new P_Key Table object
    of the specified size.
    NULL otherwise.

OpenSM/Physical Port

    Physical Port

    The Physical Port object encapsulates the information needed by the
    OpenSM to manage physical ports.  The OpenSM allocates one Physical Port
    per physical port in the IBA subnet.

    In a switch, one multiple Physical Port objects share the same port GUID.
    In an end-point, Physical Ports do not share GUID values.

    The Physical Port is not thread safe, thus callers must provide
    serialization.

    These objects should be treated as opaque and should be
    manipulated only through the provided functions.

    Steve King, Intel

OpenSM: Physical Port/osm_physp_t

    osm_physp_t

    This object represents a physical port on a switch, router or end-point.

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

typedef struct _osm_physp
{
    ib_port_info_t                      port_info;
    ib_net64_t                          port_guid;
    uint8_t                             port_num;
    struct _osm_node                    *p_node;
    struct _osm_physp                   *p_remote_physp;
    osm_dr_path_t                       dr_path;
    osm_pkey_tbl_t                      *p_pkey_tbl;

} osm_physp_t;

    port_info
        The IBA defined PortInfo data for this port.

    port_guid
        Port GUID value of this port.  For switches,
        all ports share the same GUID value.

    port_num
        The port number of this port.  The PortInfo also
        contains a port_number, but that number is not
        the port number of this port, but rather the number
        of the port that received the SMP during discovery.
        Therefore, we must keep a seperate record for this
        port's port number.

    p_node
        Pointer to the parent Node object of this Physical Port.

    p_remote_physp
        Pointer to the Physical Port on the other side of the wire.
        If this pointer is NULL no link exists at this port.

    dr_path
        The directed route path to this port.

    p_pkey_tbl
        Pointer to the P_Key table for this port.

    Port

OpenSM: Physical Port/osm_physp_construct

    osm_physp_construct

    Constructs a Physical Port.

void
osm_physp_construct(
    IN osm_physp_t* const p_physp );

    p_physp
        [in] Pointer to an osm_physp_t object to initialize.

    This function does not return a value.

    Port, Physical Port

OpenSM: Physical Port/osm_physp_init

    osm_physp_init

    Initializes a Physical Port for use.

void
osm_physp_init(
    IN osm_physp_t* const p_physp,
    IN const ib_net64_t port_guid,
    IN const uint8_t port_num,
    IN const struct _osm_node* const p_node,
    IN const osm_bind_handle_t h_bind,
    IN const uint8_t hop_count,
    IN const uint8_t* const p_initial_path );

    p_physp
        [in] Pointer to an osm_physp_t object to initialize.

    port_guid
        [in] GUID value of this port.  Switch ports all share
        the same value.
        Caller should use 0 if the guid is unknown.

    port_num
        [in] The port number of this port.

    p_node
        [in] Pointer to the parent Node object of this Physical Port.

    h_bind
        [in] Bind handle on which this port is accessed.
        Caller should use OSM_INVALID_BIND_HANDLE if the bind
        handle to this port is unknown.

    hop_count
        [in] Directed route hop count to reach this port.
        Caller should use 0 if the hop count is unknown.

    p_initial_path
        [in] Pointer to the directed route path to reach this node.
        Caller should use NULL if the path is unknown.

    This function does not return a value.

    Port, Physical Port

OpenSM: Physical Port/osm_physp_is_valid

    osm_physp_is_valid

    Returns TRUE if the Physical Port has been successfully initialized.
    FALSE otherwise.

 boolean_t
osm_physp_is_valid(
    IN const osm_physp_t* const p_physp );

    p_physp
        [in] Pointer to an osm_physp_t object.

    Returns TRUE if the Physical Port has been successfully initialized.
    FALSE otherwise.

    Port, Physical Port

OpenSM: Physical Port/osm_physp_set_port_info

    osm_physp_set_port_info

    Copies the PortInfo attribute into the Physical Port object.

 void
osm_physp_set_port_info(
    IN osm_physp_t* const p_physp,
    IN const ib_port_info_t* const p_pi );

    p_physp
        [in] Pointer to an osm_physp_t object.

    p_pi
        [in] Pointer to the IBA defined PortInfo at this port number.

    This function does not return a value.

    Port, Physical Port

OpenSM: Physical Port/osm_physp_get_remote

    osm_physp_get_remote

    Returns a pointer to the Physical Port on the other side the wire.

 osm_physp_t*
osm_physp_get_remote(
    IN osm_physp_t* const p_physp );

    p_physp
        [in] Pointer to an osm_physp_t object.

    Returns a pointer to the Physical Port on the other side of
    the wire.  A return value of NULL means there is no link at this port.

    Port, Physical Port

OpenSM: Physical Port/osm_physp_get_port_guid

    osm_physp_get_port_guid

    Returns the port guid of this physical port.

 ib_net64_t
osm_physp_get_port_guid(
    IN osm_physp_t* const p_physp );

    p_physp
        [in] Pointer to an osm_physp_t object.

    Returns the port guid of this physical port.

    Port, Physical Port

OpenSM: Physical Port/osm_physp_link

    osm_physp_link

    Sets the pointers to the Physical Ports on the other side the wire.

 void
osm_physp_link(
    IN osm_physp_t* const p_physp,
    IN osm_physp_t* const p_neighbor_physp );

    p_physp
        [in] Pointer to an osm_physp_t object to link.

    p_neighbor_physp
        [in] Pointer to the adjacent osm_physp_t object to link.

    Returns a pointer to the Physical Port on the other side of
    the wire.  A return value of NULL means there is no link at this port.

    Port, Physical Port

OpenSM: Physical Port/osm_physp_link_exists

    osm_physp_link_exists

    Returns TRUE if the Physical Port has a link to the specified port.
    FALSE otherwise.

 boolean_t
osm_physp_link_exists(
    IN const osm_physp_t* const p_physp,
    IN const osm_physp_t* const p_neighbor_physp );

    p_physp
        [in] Pointer to an osm_physp_t object.

    p_neighbor_physp
        [in] Pointer to an osm_physp_t object.

    Returns TRUE if the Physical Port has a link to another port.
    FALSE otherwise.

    Port, Physical Port

OpenSM: Physical Port/osm_physp_has_any_link

    osm_physp_has_any_link

    Returns TRUE if the Physical Port has a link to another port.
    FALSE otherwise.

 boolean_t
osm_physp_has_any_link(
    IN const osm_physp_t* const p_physp );

    p_physp
        [in] Pointer to an osm_physp_t object.

    Returns TRUE if the Physical Port has a link to another port.
    FALSE otherwise.

    Port, Physical Port

OpenSM: Physical Port/osm_physp_get_port_num

    osm_physp_get_port_num

    Returns the local port number of this Physical Port.

 uint8_t
osm_physp_get_port_num(
    IN const osm_physp_t* const p_physp );

    p_physp
        [in] Pointer to an osm_physp_t object.

    Returns the local port number of this Physical Port.

OpenSM: Physical Port/osm_physp_get_port_info_ptr

    osm_physp_get_port_info_ptr

    Returns a pointer to the PortInfo attribute for this port.

 ib_port_info_t*
osm_physp_get_port_info_ptr(
    IN const osm_physp_t* const p_physp );

    p_physp
        [in] Pointer to an osm_physp_t object.

    Returns a pointer to the PortInfo attribute for this port.

OpenSM: Physical Port/osm_physp_get_node_ptr

    osm_physp_get_node_ptr

    Returns a pointer to the parent Node object for this port.

 struct _osm_node*
osm_physp_get_node_ptr(
    IN const osm_physp_t* const p_physp );

    p_physp
        [in] Pointer to an osm_physp_t object.

    Returns a pointer to the parent Node object for this port.

OpenSM: Physical Port/osm_physp_get_port_state

    osm_physp_get_port_state

    Returns the port state of this Physical Port.

 uint8_t
osm_physp_get_port_state(
    IN const osm_physp_t* const p_physp );

    p_physp
        [in] Pointer to an osm_physp_t object.

    Returns the local port number of this Physical Port.

OpenSM: Physical Port/osm_physp_get_base_lid

    osm_physp_get_base_lid

    Returns the base lid of this Physical Port.

 ib_net16_t
osm_physp_get_base_lid(
    IN const osm_physp_t* const p_physp );

    p_physp
        [in] Pointer to an osm_physp_t object.

    Returns the base lid of this Physical Port.

OpenSM: Physical Port/osm_physp_get_lmc

    osm_physp_get_lmc

    Returns the LMC value of this Physical Port.

 uint8_t
osm_physp_get_lmc(
    IN const osm_physp_t* const p_physp );

    p_physp
        [in] Pointer to an osm_physp_t object.

    Returns the LMC value of this Physical Port.

OpenSM: Physical Port/osm_physp_get_dr_path_ptr

    osm_physp_get_dr_path_ptr

    Returns a pointer to the directed route path for this port.

 osm_dr_path_t*
osm_physp_get_dr_path_ptr(
    IN const osm_physp_t* const p_physp );

    p_physp
        [in] Pointer to a Physical Port object.

    Returns a pointer to the directed route path for this port.

    Physical Port object

OpenSM/Port

    Port

    The Port object encapsulates the information needed by the
    OpenSM to manage ports.  The OpenSM allocates one Port object
    per port in the IBA subnet.

    Each Port object is associated with a single port GUID.  A Port object
    contains 1 or more Physical Port objects.  An end point node has
    one Physical Port per Port.  A switch node has more than
    one Physical Port per Port.

    The Port object is not thread safe, thus callers must provide
    serialization.

    These objects should be treated as opaque and should be
    manipulated only through the provided functions.

    Steve King, Intel

OpenSM: Port/osm_port_lid_category_t

    osm_port_lid_category_t

    Enumerated values for LID dispostion.

typedef enum _osm_port_lid_category
{
    OSM_PORT_LID_ASSIGNED = 0,
    OSM_PORT_LID_UNASSIGNED,
    OSM_PORT_LID_CONFLICT,
    OSM_PORT_LID_FOREIGN,

} osm_port_lid_category_t;

    OSM_PORT_LID_ASSIGNED
        Indicates the Port has a known LID value.

    OSM_PORT_LID_UNASSIGNED
        Indicates the Port does not have a LID value.

    OSM_PORT_LID_CONFLICT
        Indicates the Port's LID conflicts with an assigned LID.

    OSM_PORT_LID_FOREIGN
        Indicates the Port has a LID value not currently known in
        in the OpenSM LID database.

    Port

OpenSM: Port/osm_port_t

    osm_port_t

    This object represents a logical port on a switch, router or end-point.

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

typedef struct _osm_port
{
    cl_map_item_t                       map_item;
    struct _osm_node                    *p_node;
    ib_net64_t                          guid;
    uint8_t                             default_port_num;
    uint8_t                             port_tbl_size;
    osm_physp_t                         *tbl[1];

} osm_port_t;

    map_item
        Linkage structure for cl_qmap.  MUST BE FIRST MEMBER!

    p_node
        Points to the Node object that owns this port.

    guid
        Manufacturer assigned GUID for this port.

    default_port_num
        Index of the physical port used when physical charactereistics
        contained in the Physical Port are needed.

    port_tbl_size
        Number of physical ports associated with this logical port.

    tbl
        Array of pointers to Physical Port objects contained by this node.

    Port, Physical Port, Physical Port Table

OpenSM: Port/osm_port_construct

    osm_port_construct

    This function constructs a Port object.

 void
osm_port_construct(
    IN osm_port_t* const p_port );

    p_port
        [in] Pointer to a Port oject to construct.

    This function does not return a value.

    Allows calling osm_port_init, osm_port_destroy, and osm_port_is_inited.

    Calling osm_port_construct is a prerequisite to calling any other
    method except osm_port_init.

    Port, osm_port_init, osm_port_destroy, osm_port_is_inited

OpenSM: Port/osm_port_destroy

    osm_port_destroy

    This function destroys a Port object.

inline static void
osm_port_destroy(
    IN osm_port_t* const p_port );

    p_port
        [in] Pointer to a Port oject to construct.

    This function does not return a value.

    Performs any necessary cleanup of the specified Port object.
    Further operations should not be attempted on the destroyed object.
    This function should only be called after a call to osm_port_construct or
    osm_port_init.

    Port, osm_port_init, osm_port_destroy, osm_port_is_inited

OpenSM: Port/osm_port_destroy

    osm_port_destroy

    This function destroys and deallocates a Port object.

inline static void
osm_port_delete(
    IN OUT osm_port_t** const pp_port );

    pp_port
        [in][out] Pointer to a pointer to a Port oject to delete.
        On return, this pointer is NULL.

    This function does not return a value.

    Performs any necessary cleanup of the specified Port object.

    Port, osm_port_init, osm_port_destroy

OpenSM: Port/osm_port_init

    osm_port_init

    This function initializes a Port object.

void
osm_port_init(
    IN osm_port_t* const p_port,
    IN const ib_node_info_t* p_ni,
    IN const struct _osm_node* const p_parent_node );

    p_port
        [in] Pointer to a Port oject to initialize.

    p_ni
        [in] Pointer to the NodeInfo attribute relavent for this port.

    p_parent_node
        [in] Pointer to the initialized parent osm_node_t object
        that owns this port.

    None.

    Allows calling other port methods.

    Port

OpenSM: Port/osm_port_new

    osm_port_new

    This function allocates and initializes a Port object.

osm_port_t*
osm_port_new(
    IN const ib_node_info_t* p_ni,
    IN const struct _osm_node* const p_parent_node );

    p_ni
        [in] Pointer to the NodeInfo attribute relavent for this port.

    p_parent_node
        [in] Pointer to the initialized parent osm_node_t object
        that owns this port.

    Pointer to the initialize Port object.

    Allows calling other port methods.

    Port

OpenSM: Port/osm_port_get_base_lid

    osm_port_get_base_lid

    Gets the base LID of a port.

 ib_net16_t
osm_port_get_base_lid(
    IN const osm_port_t* const p_port );

    p_port
        [in] Pointer to a Port oject.

    Base LID of the port.
    If the return value is 0, then this port has no assigned LID.

    Port

OpenSM: Port/osm_port_get_lmc

    osm_port_get_lmc

    Gets the LMC value of a port.

 uint8_t
osm_port_get_lmc(
    IN const osm_port_t* const p_port );

    p_port
        [in] Pointer to a Port oject.

    Gets the LMC value of a port.

    Port

OpenSM: Port/osm_port_get_guid

    osm_port_get_guid

    Gets the GUID of a port.

 ib_net64_t
osm_port_get_guid(
    IN const osm_port_t* const p_port );

    p_port
        [in] Pointer to a Port oject.

    Manufacturer assigned GUID of the port.

    Port

OpenSM: Port/osm_port_get_phys_ptr

    osm_port_get_phys_ptr

    Gets the pointer to the specified Physical Port object.

 osm_physp_t*
osm_port_get_phys_ptr(
    IN const osm_port_t* const p_port,
    IN const uint8_t port_num );

    p_port
        [in] Pointer to a Port oject.

    port_num
        [in] Number of physical port for which to return the
        osm_physp_t object.  If this port is on an HCA, then
        this value is ignored.

    Pointer to the Physical Port object.

    Port

OpenSM: Port/osm_port_get_parent_node

    osm_port_get_parent_node

    Gets the pointer to the specified Physical Port object.

 struct _osm_node*
osm_port_get_parent_node(
    IN const osm_port_t* const p_port );

    p_port
        [in] Pointer to a Port oject.

    port_num
        [in] Number of physical port for which to return the
        osm_physp_t object.

    Pointer to the Physical Port object.

    Port

OpenSM: Physical Port/osm_physp_get_parent_node

    osm_physp_get_parent_node

    Returns the parent node of this physical port.

 struct _osm_node*
osm_physp_get_parent_node(
    IN const osm_physp_t* const p_physp );

    p_physp
        [in] Pointer to an osm_physp_t object.

    Returns the parent node of this physical port.

OpenSM: Port/osm_port_categorize_lid

    osm_port_categorize_lid

    Returns an OSM_PORT_LID_XXX enum representing the disposition
    of this Port's LID.

osm_port_lid_category_t
osm_port_categorize_lid(
    IN const osm_port_t* const p_port,
    IN const cl_ptr_vector_t* const p_tbl,
    IN const uint8_t opensm_lmc );

    p_port
        [in] Pointer to a Port oject.

    p_tbl
        [in] Pointer to the port LID vector.

    opensm_lmc
        [in] The LMC value currently used by the subnet.

    Returns an OSM_PORT_LID_XXX enum representing the disposition
    of this Port's LID.

    Port

OpenSM: Port/osm_port_get_lid_range_ho

    osm_port_get_lid_range_ho

    Returns the HOST ORDER lid min and max values for this port,
    based on the lmc value.

void
osm_port_get_lid_range_ho(
    IN const osm_port_t* const p_port,
    OUT uint16_t* const p_min_lid,
    OUT uint16_t* const p_max_lid );

    p_port
        [in] Pointer to a Port oject.

    p_min_lid
        [out] Pointer to the minimum LID value occupied by this port.

    p_max_lid
        [out] Pointer to the maximum LID value occupied by this port.

    None.

    Port

OpenSM: Port/osm_port_add_new_physp

    osm_port_add_new_physp

    Adds a new physical port to the logical collection owned by the Port.
    Physical Ports added here must share the same GUID as the Port.

void
osm_port_add_new_physp(
    IN osm_port_t* const p_port,
    IN const uint8_t port_num );

    p_port
        [in] Pointer to a Port oject.

    port_num
        [in] Port number to add.

    None.

    Port