TABLE OF CONTENTS

1. OpenSM/MAD Pool
2. OpenSM: MAD Pool/osm_mad_pool_t
3. OpenSM: MAD Pool/osm_mad_pool_construct
4. OpenSM: MAD Pool/osm_mad_pool_destroy
5. OpenSM: MAD Pool/osm_mad_pool_init
6. OpenSM: MAD Pool/osm_mad_pool_is_inited
7. OpenSM: MAD Pool/osm_mad_pool_get
8. OpenSM: MAD Pool/osm_mad_pool_put
9. OpenSM: MAD Pool/osm_mad_pool_get_wrapper
10. OpenSM: MAD Pool/osm_mad_pool_get_outstanding

OpenSM/MAD Pool

    MAD Pool

    The MAD Pool encapsulates the information needed by the
    OpenSM to manage a pool of MAD objects.  The OpenSM allocates
    one MAD Pool per IBA subnet.

    The MAD Pool is thread safe.

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

    Steve King, Intel

OpenSM: MAD Pool/osm_mad_pool_t

    osm_mad_pool_t

    MAD Pool structure.

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

typedef struct _osm_mad_pool_t
{
    osm_log_t                   *p_log;
    cl_spinlock_t               lock;
    cl_qpool_t                  madw_pool;
    uint32_t                    mads_out;
} osm_mad_pool_t;

    p_log
        Pointer to the log object.

    lock
        Spinlock guarding the pool.

    mads_out
        Running total of the number of MADs outstanding.

    MAD Pool

OpenSM: MAD Pool/osm_mad_pool_construct

    osm_mad_pool_construct

    This function constructs a MAD Pool.

void osm_mad_pool_construct(
    IN osm_mad_pool_t* const p_pool );

    p_pool
        [in] Pointer to a MAD Pool to construct.

    This function does not return a value.

    Allows calling osm_mad_pool_init, osm_mad_pool_destroy, and
    osm_mad_pool_is_inited.

    Calling osm_mad_pool_construct is a prerequisite to calling any other
    method except osm_mad_pool_init.

    MAD Pool, osm_mad_pool_init, osm_mad_pool_destroy, osm_mad_pool_is_inited

OpenSM: MAD Pool/osm_mad_pool_destroy

    osm_mad_pool_destroy

    The osm_mad_pool_destroy function destroys a node, releasing
    all resources.

void osm_mad_pool_destroy(
    IN osm_mad_pool_t* const p_pool );

    p_pool
        [in] Pointer to a MAD Pool to destroy.

    This function does not return a value.

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

    MAD Pool, osm_mad_pool_construct, osm_mad_pool_init

OpenSM: MAD Pool/osm_mad_pool_init

    osm_mad_pool_init

    The osm_mad_pool_init function initializes a MAD Pool for use.

ib_api_status_t osm_mad_pool_init(
    IN osm_mad_pool_t* const p_pool,
    IN osm_log_t* const p_log );

    p_pool
        [in] Pointer to an osm_mad_pool_t object to initialize.

    p_log
        [in] Pointer to the log object.

    CL_SUCCESS if the MAD Pool was initialized successfully.

    Allows calling other MAD Pool methods.

    MAD Pool, osm_mad_pool_construct, osm_mad_pool_destroy,
    osm_mad_pool_is_inited

OpenSM: MAD Pool/osm_mad_pool_is_inited

    osm_mad_pool_is_inited

    Indicates if the object has been initialized with osm_mad_pool_init.

boolean_t osm_mad_pool_is_inited(
    IN const osm_mad_pool_t* const p_pool );

    p_pool
        [in] Pointer to an osm_mad_pool_t object.

    TRUE if the object was initialized successfully,
    FALSE otherwise.

    The osm_mad_pool_construct or osm_mad_pool_init must be called before
    using this function.

    MAD Pool, osm_mad_pool_construct, osm_mad_pool_init

OpenSM: MAD Pool/osm_mad_pool_get

    osm_mad_pool_get

    Gets a MAD wrapper and wire MAD from the pool.

osm_madw_t*
osm_mad_pool_get(
    IN osm_mad_pool_t* const p_pool,
    IN osm_bind_handle_t h_bind,
    IN const uint32_t total_size,
    IN const osm_mad_addr_t* const p_mad_addr );

    p_pool
        [in] Pointer to an osm_mad_pool_t object.

    h_bind
        [in] Handle returned from osm_vendor_bind() call to the
        port over which this mad will be sent.

    total_size
        [in] Total size, including MAD header of the requested MAD.

    p_mad_addr
        [in] Pointer to the MAD address structure.  This parameter
        may be NULL for directed route MADs.

    Returns a pointer to a MAD wrapper containing the MAD.
    A return value of NULL means no MADs are available.

    The MAD must eventually be returned to the pool with a call to
    osm_mad_pool_put.

    The osm_mad_pool_construct or osm_mad_pool_init must be called before
    using this function.

    MAD Pool, osm_mad_pool_put

OpenSM: MAD Pool/osm_mad_pool_put

    osm_mad_pool_put

    Returns a MAD to the pool.

void osm_mad_pool_put(
    IN osm_mad_pool_t* const p_pool,
    IN osm_madw_t* const p_madw );

    p_pool
        [in] Pointer to an osm_mad_pool_t object.

    p_madw
        [in] Pointer to a MAD Wrapper for a MAD that was previously
        retrieved from the pool.

    This function does not return a value.

    The osm_mad_pool_construct or osm_mad_pool_init must be called before
    using this function.

    MAD Pool, osm_mad_pool_get

OpenSM: MAD Pool/osm_mad_pool_get_wrapper

    osm_mad_pool_get_wrapper

    Gets a only MAD wrapper from the pool (no wire MAD).

osm_madw_t*
osm_mad_pool_get_wrapper(
    IN osm_mad_pool_t* const p_pool,
    IN osm_bind_handle_t h_bind,
    IN const uint32_t total_size,
    IN const ib_mad_t* const p_mad,
    IN const osm_mad_addr_t* const p_mad_addr );

    p_pool
        [in] Pointer to an osm_mad_pool_t object.

    h_bind
        [in] Handle returned from osm_vendor_bind() call to the
        port for which this mad wrapper will be used.

    total_size
        [in] Total size, including MAD header of the MAD that will
        be attached to this wrapper.

    p_mad
        [in] Pointer to the MAD to attach to this wrapper.

    p_mad_addr
        [in] Pointer to the MAD address structure.  This parameter
        may be NULL for directed route MADs.

    Returns a pointer to a MAD wrapper containing the specified MAD.
    A return value of NULL means no MAD wrappers are available.

    The MAD must eventually be returned to the pool with a call to
    osm_mad_pool_put.

    The osm_mad_pool_construct or osm_mad_pool_init must be called before
    using this function.

    MAD Pool, osm_mad_pool_put

OpenSM: MAD Pool/osm_mad_pool_get_outstanding

    osm_mad_pool_get_count

    Returns the running count of MADs currently outstanding from the pool.

 uint32_t
osm_mad_pool_get_outstanding(
    IN const osm_mad_pool_t* const p_pool );

    p_pool
        [in] Pointer to an osm_mad_pool_t object.

    Returns the running count of MADs currently outstanding from the pool.

    The osm_mad_pool_construct or osm_mad_pool_init must be called before
    using this function.

    MAD Pool, osm_mad_pool_get