TABLE OF CONTENTS

1. OpenSM/Forwarding Table
2. OpenSM: Forwarding Table/osm_lin_fwd_tbl_t
3. OpenSM: Forwarding Table/osm_lin_tbl_new
4. OpenSM: Forwarding Table/osm_lin_tbl_delete
5. OpenSM: Forwarding Table/osm_lin_fwd_tbl_set
6. OpenSM: Forwarding Table/osm_lin_fwd_tbl_get
7. OpenSM: Forwarding Table/osm_lin_fwd_tbl_get_size
8. OpenSM: Forwarding Table/osm_lin_fwd_tbl_get_lids_per_block
9. OpenSM: Forwarding Table/osm_rand_fwd_tbl_t
10. OpenSM: Forwarding Table/osm_rand_tbl_delete
11. OpenSM: Forwarding Table/osm_rand_fwd_tbl_set
12. OpenSM: Forwarding Table/osm_rand_fwd_tbl_get
13. OpenSM: Forwarding Table/osm_rand_fwd_tbl_get_lids_per_block
14. OpenSM: Forwarding Table/osm_rand_fwd_tbl_get_size
15. OpenSM: Forwarding Table/osm_fwd_tbl_t
16. OpenSM: Forwarding Table/osm_fwd_tbl_init
17. OpenSM: Forwarding Table/osm_fwd_tbl_destroy
18. OpenSM: Forwarding Table/osm_fwd_tbl_get
19. OpenSM: Forwarding Table/osm_fwd_tbl_set
20. OpenSM: Forwarding Table/osm_fwd_tbl_get_size
21. OpenSM: Forwarding Table/osm_fwd_tbl_get_lids_per_block
22. OpenSM/Switch
23. OpenSM: Switch/osm_switch_t
24. OpenSM: Switch/osm_switch_construct
25. OpenSM: Switch/osm_switch_destroy
26. OpenSM: Switch/osm_switch_destroy
27. OpenSM: Switch/osm_switch_init
28. OpenSM: Switch/osm_switch_new
29. OpenSM: Switch/osm_switch_is_leaf_lid
30. OpenSM: Switch/osm_switch_get_hop_count
31. OpenSM: Switch/osm_switch_get_fwd_tbl_ptr
32. OpenSM: Switch/osm_switch_set_hops
33. OpenSM: Switch/osm_switch_set_hops
34. OpenSM: Switch/osm_switch_get_least_hops
35. OpenSM: Switch/osm_switch_get_port_by_lid
36. OpenSM: Switch/osm_switch_get_lid
37. OpenSM: Switch/osm_switch_get_physp_ptr
38. OpenSM: Switch/osm_switch_get_route_by_lid
39. OpenSM: Switch/osm_switch_get_lid_matrix_ptr
40. OpenSM: Switch/osm_switch_get_node_ptr
41. OpenSM: LID Matrix/osm_switch_get_max_lid_ho
42. OpenSM: LID Matrix/osm_switch_get_num_ports
43. OpenSM: LID Matrix/osm_switch_get_num_ports
44. OpenSM: Switch/osm_switch_set_switch_info

OpenSM/Forwarding Table

    Forwarding Table

    The Forwarding Table objects encapsulate the information
    needed by the OpenSM to manage forwarding tables.  The OpenSM
    allocates one Forwarding Table object per switch in the
    IBA subnet.

    The Forwarding Table objects are not thread safe, thus
    callers must provide serialization.

    Steve King, Intel

OpenSM: Forwarding Table/osm_lin_fwd_tbl_t

    osm_lin_fwd_tbl_t

    Linear Forwarding Table structure.

    Callers may directly access this object.

typedef struct _osm_lin_fwd_tbl
{
    uint16_t                size;
    uint8_t                 port_tbl[1];

} osm_lin_fwd_tbl_t;

    Size
        Number of entries in the linear forwarding table.  This value
        is taken from the SwitchInfo attribute.

    port_tbl
        The array that specifies the port number which routes the
        corresponding LID.  Index is by LID.

    Forwarding Table object, Random Fowarding Table object.

OpenSM: Forwarding Table/osm_lin_tbl_new

    osm_lin_tbl_new

    This function creates and initializes a Linear Forwarding Table object.

osm_lin_fwd_tbl_t*
osm_lin_tbl_new(
    IN uint16_t const size );

    size
        [in] Number of entries in the Linear Forwarding Table.

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

OpenSM: Forwarding Table/osm_lin_tbl_delete

    osm_lin_tbl_delete

    This destroys and deallocates a Linear Forwarding Table object.

void
osm_lin_tbl_delete(
    IN osm_lin_fwd_tbl_t** const pp_tbl );

    pp_tbl
        [in] Pointer a Pointer to the Linear Forwarding Table object.

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

OpenSM: Forwarding Table/osm_lin_fwd_tbl_set

    osm_lin_fwd_tbl_set

    Sets the port to route the specified LID.

 void
osm_lin_fwd_tbl_set(
    IN osm_lin_fwd_tbl_t* const p_tbl,
    IN const uint16_t lid_ho,
    IN const uint8_t port );

    p_tbl
        [in] Pointer to the Linear Forwarding Table object.

    lid_ho
        [in] LID value (host order) for which to set the route.

    port
        [in] Port to route the specified LID value.

    None.

OpenSM: Forwarding Table/osm_lin_fwd_tbl_get

    osm_lin_fwd_tbl_get

    Returns the port that routes the specified LID.

 uint8_t
osm_lin_fwd_tbl_get(
    IN const osm_lin_fwd_tbl_t* const p_tbl,
    IN const uint16_t lid_ho );

    p_tbl
        [in] Pointer to the Linear Forwarding Table object.

    lid_ho
        [in] LID value (host order) for which to get the route.

    Returns the port that routes the specified LID.

OpenSM: Forwarding Table/osm_lin_fwd_tbl_get_size

    osm_lin_fwd_tbl_get_size

    Returns the number of entries available in the forwarding table.

 uint16_t
osm_lin_fwd_tbl_get_size(
    IN const osm_lin_fwd_tbl_t* const p_tbl );

    p_tbl
        [in] Pointer to the Forwarding Table object.

    Returns the number of entries available in the forwarding table.

OpenSM: Forwarding Table/osm_lin_fwd_tbl_get_lids_per_block

    osm_lin_fwd_tbl_get_lids_per_block

    Returns the number of LIDs per LID block.

 uint16_t
osm_lin_fwd_tbl_get_lids_per_block(
    IN const osm_lin_fwd_tbl_t* const p_tbl );

    p_tbl
        [in] Pointer to the Forwarding Table object.

    Returns the number of LIDs per LID block.

OpenSM: Forwarding Table/osm_rand_fwd_tbl_t

    osm_rand_fwd_tbl_t

    Random Forwarding Table structure.

    THIS OBJECT IS PLACE HOLDER.  SUPPORT FOR SWITCHES WITH
    RANDOM FORWARDING TABLES HAS NOT BEEN IMPLEMENTED YET.

typedef struct _osm_rand_fwd_tbl
{
    /* PLACE HOLDER STRUCTURE ONLY!! */
    uint32_t                size;

} osm_rand_fwd_tbl_t;

    RANDOM FORWARDING TABLES ARE NOT SUPPORTED YET!!

    Forwarding Table object, Random Fowarding Table object.

OpenSM: Forwarding Table/osm_rand_tbl_delete

    osm_rand_tbl_delete

    This destroys and deallocates a Random Forwarding Table object.

void
osm_rand_tbl_delete(
    IN osm_rand_fwd_tbl_t** const pp_tbl );

    pp_tbl
        [in] Pointer a Pointer to the Random Forwarding Table object.

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

OpenSM: Forwarding Table/osm_rand_fwd_tbl_set

    osm_rand_fwd_tbl_set

    Sets the port to route the specified LID.

 void
osm_rand_fwd_tbl_set(
    IN osm_rand_fwd_tbl_t* const p_tbl,
    IN const uint16_t lid_ho,
    IN const uint8_t port );

    p_tbl
        [in] Pointer to the Random Forwarding Table object.

    lid_ho
        [in] LID value (host order) for which to set the route.

    port
        [in] Port to route the specified LID value.

    None.

OpenSM: Forwarding Table/osm_rand_fwd_tbl_get

    osm_rand_fwd_tbl_get

    Returns the port that routes the specified LID.

 uint8_t
osm_rand_fwd_tbl_get(
    IN const osm_rand_fwd_tbl_t* const p_tbl,
    IN const uint16_t lid_ho );

    p_tbl
        [in] Pointer to the Linear Forwarding Table object.

    lid_ho
        [in] LID value (host order) for which to get the route.

    Returns the port that routes the specified LID.

OpenSM: Forwarding Table/osm_rand_fwd_tbl_get_lids_per_block

    osm_rand_fwd_tbl_get_lids_per_block

    Returns the number of LIDs per LID block.

 uint16_t
osm_rand_fwd_tbl_get_lids_per_block(
    IN const osm_rand_fwd_tbl_t* const p_tbl );

    p_tbl
        [in] Pointer to the Forwarding Table object.

    Returns the number of LIDs per LID block.

OpenSM: Forwarding Table/osm_rand_fwd_tbl_get_size

    osm_rand_fwd_tbl_get_size

    Returns the number of entries available in the forwarding table.

 uint16_t
osm_rand_fwd_tbl_get_size(
    IN const osm_rand_fwd_tbl_t* const p_tbl );

    p_tbl
        [in] Pointer to the Forwarding Table object.

    Returns the number of entries available in the forwarding table.

OpenSM: Forwarding Table/osm_fwd_tbl_t

    osm_fwd_tbl_t

    Forwarding Table structure.  This object hides the type
    of fowarding table (linear or random) actually used by
    the switch.

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

typedef struct _osm_fwd_tbl_t
{
    osm_rand_fwd_tbl_t  *p_rnd_tbl;
    osm_lin_fwd_tbl_t   *p_lin_tbl;

} osm_fwd_tbl_t;

    p_rnd_tbl
        Pointer to the switch's Random Forwarding Table object.
        If the switch does not use a Random Forwarding Table,
        then this pointer is NULL.

    p_lin_tbl
        Pointer to the switch's Linear Forwarding Table object.
        If the switch does not use a Linear Forwarding Table,
        then this pointer is NULL.

    Forwarding Table object, Random Fowarding Table object.

OpenSM: Forwarding Table/osm_fwd_tbl_init

    osm_fwd_tbl_init

    Initializes a Forwarding Table object.

ib_api_status_t
osm_fwd_tbl_init(
    IN osm_fwd_tbl_t* const p_tbl,
    IN const ib_switch_info_t* const p_si );

    p_tbl
        [in] Pointer to the Forwarding Table object.

    linear
        [in] TRUE if the switch uses a Linear Forwarding Table.
        FALSE otherwise.    

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

    IB_SUCCESS if the operation is successful.

OpenSM: Forwarding Table/osm_fwd_tbl_destroy

    osm_fwd_tbl_destroy

    Destroys a Forwarding Table object.

void
osm_fwd_tbl_destroy(
    IN osm_fwd_tbl_t* const p_tbl );

    p_tbl
        [in] Pointer to the Forwarding Table object.

    None.

OpenSM: Forwarding Table/osm_fwd_tbl_get

    osm_fwd_tbl_get

    Returns the port that routes the specified LID.

 uint8_t
osm_fwd_tbl_get(
    IN const osm_fwd_tbl_t* const p_tbl,
    IN uint16_t const lid_ho );

    p_tbl
        [in] Pointer to the Forwarding Table object.

    lid_ho
        [in] LID (host order) for which to find the route.

    Returns the port that routes the specified LID.
    IB_INVALID_PORT_NUM if the table does not have a route for this LID.

OpenSM: Forwarding Table/osm_fwd_tbl_set

    osm_fwd_tbl_set

    Sets the port to route the specified LID.

 void
osm_fwd_tbl_set(
    IN osm_fwd_tbl_t* const p_tbl,
    IN const uint16_t lid_ho,
    IN const uint8_t port );

    p_tbl
        [in] Pointer to the Forwarding Table object.

    lid_ho
        [in] LID value (host order) for which to set the route.

    port
        [in] Port to route the specified LID value.

    None.

OpenSM: Forwarding Table/osm_fwd_tbl_get_size

    osm_fwd_tbl_get_size

    Returns the number of entries available in the forwarding table.

 uint16_t
osm_fwd_tbl_get_size(
    IN const osm_fwd_tbl_t* const p_tbl );

    p_tbl
        [in] Pointer to the Forwarding Table object.

    Returns the number of entries available in the forwarding table.

OpenSM: Forwarding Table/osm_fwd_tbl_get_lids_per_block

    osm_fwd_tbl_get_lids_per_block

    Returns the number of LIDs per LID block.

 uint16_t
osm_fwd_tbl_get_lids_per_block(
    IN const osm_fwd_tbl_t* const p_tbl );

    p_tbl
        [in] Pointer to the Forwarding Table object.

    Returns the number of LIDs per LID block.

OpenSM/Switch

    Switch

    The Switch object encapsulates the information needed by the
    OpenSM to manage switches.  The OpenSM allocates one switch object
    per switch in the IBA subnet.

    The Switch object 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: Switch/osm_switch_t

    osm_switch_t

    Switch structure.

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

typedef struct _osm_switch_t
{
    cl_map_item_t               map_item;
    osm_node_t                  *p_node;
    ib_switch_info_t            switch_info;
    osm_fwd_tbl_t               fwd_tbl;
    osm_lid_matrix_t            lmx;

} osm_switch_t;

    map_item
        Linkage structure for cl_qmap.  MUST BE FIRST MEMBER!

    p_node
        Pointer to the Node object for this switch.

    switch_info
        IBA defined SwitchInfo structure for this switch.

    fwd_tbl
        This switch's forwarding table.

    lmx
        LID Matrix for this switch containing the hop count
        to every LID from every port.

    Switch object

OpenSM: Switch/osm_switch_construct

    osm_switch_construct

    This function constructs a Switch object.

void
osm_switch_construct(
    IN osm_switch_t* const p_sw );

    p_sw
        [in] Pointer to a Switch object to construct.

    This function does not return a value.

    Allows calling osm_switch_init, osm_switch_destroy, and osm_switch_is_inited.

    Calling osm_switch_construct is a prerequisite to calling any other
    method except osm_switch_init.

    Switch object, osm_switch_init, osm_switch_destroy, osm_switch_is_inited

OpenSM: Switch/osm_switch_destroy

    osm_switch_destroy

    The osm_switch_destroy function destroys the object, releasing
    all resources.

void
osm_switch_destroy(
    IN osm_switch_t* const p_sw );

    p_sw
        [in] Pointer to the object to destroy.

    None.

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

    Switch object, osm_switch_construct, osm_switch_init

OpenSM: Switch/osm_switch_destroy

    osm_switch_destroy

    Destroys and deallocates the object.

void
osm_switch_delete(
    IN OUT osm_switch_t** const pp_sw );

    p_sw
        [in] Pointer to the object to destroy.

    None.

    Switch object, osm_switch_construct, osm_switch_init

OpenSM: Switch/osm_switch_init

    osm_switch_init

    The osm_switch_init function initializes a Switch object for use.

ib_api_status_t
osm_switch_init(
    IN osm_switch_t* const p_sw,
    IN osm_node_t* const p_node,
    IN const osm_madw_t* const p_madw );

    p_sw
        [in] Pointer to an osm_switch_t object to initialize.

    p_node
        [in] Pointer to the node object of this switch

    p_madw
        [in] Pointer to the MAD Wrapper containing the switch's
        SwitchInfo attribute.

    IB_SUCCESS if the Switch object was initialized successfully.

    Allows calling other node methods.

    Switch object, osm_switch_construct, osm_switch_destroy,
    osm_switch_is_inited

OpenSM: Switch/osm_switch_new

    osm_switch_new

    The osm_switch_init function initializes a Switch object for use.

osm_switch_t*
osm_switch_new(
    IN osm_node_t* const p_node,
    IN const osm_madw_t* const p_madw );

    p_node
        [in] Pointer to the node object of this switch

    p_madw
        [in] Pointer to the MAD Wrapper containing the switch's
        SwitchInfo attribute.

    Pointer to the new initialized switch object.

    Switch object, osm_switch_construct, osm_switch_destroy,

OpenSM: Switch/osm_switch_is_leaf_lid

    osm_switch_is_leaf_lid

    Indicates if the specified LID is the switch's LID, or is a leaf
    of the switch.

 boolean_t
osm_switch_is_leaf_lid(
    IN const osm_switch_t* const p_sw,
    IN const uint16_t lid_ho );

    p_sw
        [in] Pointer to an osm_switch_t object.

    lid_ho
        [in] LID (host order) to compare.

    TRUE if the LID is the switch's LID or is a leaf of the switch,
    FALSE otherwise.

    Switch object

OpenSM: Switch/osm_switch_get_hop_count

    osm_switch_get_hop_count

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

 uint8_t
osm_switch_get_hop_count(
    IN const osm_switch_t* const p_sw,
    IN const uint16_t lid_ho,
    IN const uint8_t port_num );

    p_sw
        [in] Pointer to a Switch 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: Switch/osm_switch_get_fwd_tbl_ptr

    osm_switch_get_fwd_tbl_ptr

    Returns a pointer to the switch's forwarding table.

 osm_fwd_tbl_t*
osm_switch_get_fwd_tbl_ptr(
    IN const osm_switch_t* const p_sw );

    p_sw
        [in] Pointer to a Switch object.

    Returns a pointer to the switch's forwarding table.

OpenSM: Switch/osm_switch_set_hops

    osm_switch_set_hops

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

 cl_status_t
osm_switch_set_hops(
    IN osm_switch_t* const p_sw,
    IN const uint16_t lid_ho,
    IN const uint8_t port_num,
    IN const uint8_t num_hops );

    p_sw
        [in] Pointer to a Switch object.

    lid_ho
        [in] LID value (host order) for which to set the count.

    port_num
        [in] port number for which to set the count.

    num_hops
        [in] value to assign to this entry.

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

OpenSM: Switch/osm_switch_set_hops

    osm_switch_set_hops

    Sets the size of the switch's routing table to at least accomodate the
    specified LID value (host ordered)

 cl_status_t
osm_switch_set_min_lid_size(
    IN osm_switch_t* const p_sw,
    IN const uint16_t lid_ho );

    p_sw
        [in] Pointer to a Switch object.

    lid_ho
        [in] LID value (host order) for which to set the count.

    Sets the size of the switch's routing table to at least accomodate the
    specified LID value (host ordered)

OpenSM: Switch/osm_switch_get_least_hops

    osm_switch_get_least_hops

    Returns the number of hops in the short path to this lid from
    any port on the switch.

 uint8_t
osm_switch_get_least_hops(
    IN const osm_switch_t* const p_sw,
    IN const uint16_t lid_ho );

    p_sw
        [in] Pointer to an osm_switch_t object.

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

    Returns the number of hops in the short path to this lid from
    any port on the switch.

    Switch object

OpenSM: Switch/osm_switch_get_port_by_lid

    osm_switch_get_port_by_lid

    Returns the switch port on which the specified LID is routed.

 uint8_t
osm_switch_get_port_by_lid(
    IN const osm_switch_t* const p_sw,
    IN const uint16_t lid_ho );

    p_sw
        [in] Pointer to an osm_switch_t object.

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

    Returns the switch port on which the specified LID is routed.

    Switch object

OpenSM: Switch/osm_switch_get_lid

    osm_switch_get_lid

    Gets the switch's LID.

ib_net16_t
osm_switch_get_lid(
    IN const osm_switch_t* const p_sw );

    p_sw
        [in] Pointer to an osm_switch_t object.

    Returns the switch's LID.  A value of zero means no LID has
    been assigned to the switch.

    Switch object

OpenSM: Switch/osm_switch_get_physp_ptr

    osm_switch_get_physp_ptr

    Gets the Port Primitive at the specified port number.

osm_physp_t*
osm_switch_get_physp_ptr(
    IN const osm_switch_t* const p_sw,
    IN const uint32_t port_num );

    p_sw
        [in] Pointer to an osm_switch_t object.

    port_num
        [in] Port number for which to retrieve the Port Primitive.

    Returns a pointer to the Port Primitive object at the specified
    port number.
    A return value of zero means the port number was out of range.
    

    Switch object

OpenSM: Switch/osm_switch_get_route_by_lid

    osm_switch_get_route_by_lid

    Gets the Port Primitive that routes the specified LID.

osm_physp_t*
osm_switch_get_route_by_lid(
    IN const osm_switch_t* const p_sw,
    IN const ib_net16_t lid );

    p_sw
        [in] Pointer to an osm_switch_t object.

    lid
        [in] LID for which to find a route.  This must be a unicast
        LID value < 0xC000.

    Returns a pointer to the Port Primitive object that
    routes the specified LID.  A return value of zero means
    there is no route for the lid through this switch.
    The lid value must be a unicast LID.
    

    Switch object

OpenSM: Switch/osm_switch_get_lid_matrix_ptr

    osm_switch_get_lid_matrix_ptr

    Returns a pointer to the LID matrix for this switch.

 osm_lid_matrix_t*
osm_switch_get_lid_matrix_ptr(
    IN const osm_switch_t* const p_sw );

    p_sw
        [in] Pointer to an osm_switch_t object.

    Returns a pointer to the LID matrix for this switch.
    

    Switch object

OpenSM: Switch/osm_switch_get_node_ptr

    osm_switch_get_node_ptr

    Returns a pointer to the Node object for this switch.

 osm_node_t*
osm_switch_get_node_ptr(
    IN const osm_switch_t* const p_sw );

    p_sw
        [in] Pointer to an osm_switch_t object.

    Returns a pointer to the LID matrix for this switch.
    

    Switch object

OpenSM: LID Matrix/osm_switch_get_max_lid_ho

    osm_switch_get_max_lid_ho

    Returns the maximum LID (host order) value contained
    in the switch routing tables.

 uint8_t
osm_switch_get_max_lid_ho(
    IN const osm_switch_t* const p_sw );

    p_sw
        [in] Pointer to a switch object.

    Returns the maximum LID (host order) value contained
    in the switch routing tables.

OpenSM: LID Matrix/osm_switch_get_num_ports

    osm_switch_get_num_ports

    Returns the number of ports in this switch.

 uint8_t
osm_switch_get_num_ports(
    IN const osm_switch_t* const p_sw );

    p_sw
        [in] Pointer to an osm_switch_t object.

    Returns the number of ports in this switch.

OpenSM: LID Matrix/osm_switch_get_num_ports

    osm_switch_get_num_ports

    Retrieve a forwarding table block.

boolean_t
osm_switch_get_fwd_tbl_block(
    IN const osm_switch_t* const p_sw,
    IN const uint32_t block_id,
    OUT uint8_t* const p_block );

    p_sw
        [in] Pointer to an osm_switch_t object.

    block_ID
        [in] The block_id to retrieve.

    p_block
        [out] Pointer to the 64 byte array to store the
        forwarding table clock specified by block_id.

    Returns true if there are more blocks necessary to 
    configure all the LIDs reachable from this switch.
    FALSE otherwise.

OpenSM: Switch/osm_switch_set_switch_info

    osm_switch_set_switch_info

    Updates the switch info attribute of this switch.

 void
osm_switch_set_switch_info(
    IN osm_switch_t* const p_sw,
    IN const ib_switch_info_t* const p_si );

    p_sw
        [in] Pointer to a Switch object.

    p_si
        [in] Pointer to the SwitchInfo attribute for this switch.

    None.