[openib-general] [PATCH] added comments to ib_mad.h - minor update
Sean Hefty
mshefty at ichips.intel.com
Thu Aug 5 12:45:42 PDT 2004
On Wed, 4 Aug 2004 16:02:13 -0700
Sean Hefty <mshefty at ichips.intel.com> wrote:
> While commenting the ib_mad_msg structure, I was wondering if it made sense to break the structure apart into multiple structures: ib_send_mad_wr, ib_mad_send_wc, ib_mad_recv_wc. Thoughts?
Here's an ib_mad.h version that breaks ib_mad_msg into multiple structures. Looking at the results, I think it makes sense to go this route. Other notable changes:
* ib_mad_reg/dereg_class() were renamed to ib_mad_reg/dereg() (suggested by Hal). Field names were changed to match ib_verbs.h (the work request/completion structures).
* ib_mad_send_wr now uses a SG-list to specify the send data. This should allow zero-copy sends, and more easily extend ib_mad_post_send() over redirected QPs.
* The new ib_mad_recv_wc structure was tweaked (based on the existing proposed GSI implementation) to allow zero-copy receives. This resulted in adding a new call, ib_free_sg_list() that can be used to deallocate the received MAD buffers. Currently, I'm not overly fond of the zero-copy receive support as defined.
Just including the file, since a diff marked nearly every line...
- Sean
/*
This software is available to you under a choice of one of two
licenses. You may choose to be licensed under the terms of the GNU
General Public License (GPL) Version 2, available at
<http://www.fsf.org/copyleft/gpl.html>, or the OpenIB.org BSD
license, available in the LICENSE.TXT file accompanying this
software. These details are also available at
<http://openib.org/license.html>.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Copyright (c) 2004 Mellanox Technologies Ltd. All rights reserved.
Copyright (c) 2004 Infinicon Corporation. All rights reserved.
Copyright (c) 2004 Intel Corporation. All rights reserved.
Copyright (c) 2004 Topspin Corporation. All rights reserved.
Copyright (c) 2004 Voltaire Corporation. All rights reserved.
*/
#if !defined( IB_MAD_H )
#define IB_MAD_H
#include "ib_verbs.h"
struct ib_mad_agent;
struct ib_mad_send_wc;
struct ib_mad_recv_wc;
typedef void (*ib_mad_send_handler)(struct ib_mad_agent *mad_agent,
struct ib_mad_send_wc *mad_send_wc);
/**
* ib_mad_recv_handler - callback handler for a received MAD.
* @mad_agent - MAD agent requesting the received MAD.
* @mad_recv_wc - Received work completion information on the received MAD.
*
* After receiving a MAD, clients must call ib_free_sg_list to release
* the data buffers associated with the MAD.
*/
typedef void (*ib_mad_recv_handler)(struct ib_mad_agent *mad_agent,
struct ib_mad_recv_wc *mad_recv_wc);
struct ib_mad_agent {
struct ib_device *device;
struct ib_qp *qp;
ib_mad_recv_handler recv_handler;
ib_mad_send_handler send_handler;
void *context;
u32 lo_tid;
};
enum ib_mad_flags {
IB_MAD_GRH_VALID = 1
};
/**
* ib_mad_send_wr - send MAD work request.
* @list - Allows chaining together multiple requests.
* @context - User-controlled work request context.
* @sg_list - An array of scatter-gather entries, referencing the MAD's
* data buffer(s). The first entry must reference a data buffer of
* 256 bytes.
* @num_sge - The number of scatter-gather entries.
* @mad_flags - Flags used to control the send operation.
* @ah - Address handle for the destination.
* @timeout_ms - Timeout value, in milliseconds, to wait for a response
* message. Set to 0 if no response is expected.
* @remote_qpn - Destination QP.
* @remote_qkey - Specifies the qkey used by remote QP.
* @pkey_index - Pkey index to use. Required when sending on QP1 only.
*/
struct ib_mad_send_wr {
struct list_head list;
void *context;
struct ib_sge *sg_list;
int num_sge;
int mad_flags;
struct ib_ah *ah;
int timeout_ms;
u32 remote_qpn;
u32 remote_qkey;
u16 pkey_index;
};
/**
* ib_mad_send_wc - MAD send completion information.
* @context - Context associated with the send MAD request.
* @status - Completion status.
* @vendor_err - Optional vendor error information returned with a failed
* request.
*/
struct ib_mad_send_wc {
void *context;
enum ib_wc_status status;
u32 vendor_err;
};
/**
* ib_mad_recv_wc - received MAD information.
* @context - For received response, set to the context specified for
* the corresponding send request.
* @sg_list - An array of scatter-gather entries, referencing the received
* MAD's data buffer(s).
* @num_sge - The number of scatter-gather entries.
* @mad_flags - Flags used to specify information about the received MAD.
* @mad_len - The length of the received MAD, without duplicated headers.
* @src_qpn - Source QP.
* @pkey_index - Pkey index.
* @slid - LID of remote QP.
* @sl - Service level of source for a received message.
* @dlid_path_bits - Path bits of source for a received message.
*
* An RMPP receive will either be coalesced into a single data buffer, or
* will be handed to the user as a list of scatter-gather entries in order
* to avoid data copies. If a list of buffers is provided to the user,
* each buffer will be 256 bytes and contain duplicated copies of the MAD
* and RMPP headers.
*/
struct ib_mad_recv_wc {
void *context;
struct ib_sge *sg_list;
int num_sge;
int mad_flags;
u32 mad_len;
u32 src_qp;
u16 pkey_index;
u16 slid;
u8 sl;
u8 dlid_path_bits;
};
/**
* ib_mad_reg_req - MAD registration request
* @mgmt_class - Indicates which management class of MADs should be receive
* by the caller. This field is only required if the user wishes to
* receive unsolicited MADs, otherwise it should be 0.
* @mgmt_class_version - Indicates which version of MADs for the given
* management class to receive.
* @method_mask - The caller will receive unsolicited MADs for any method
* where @method_mask = 1.
*/
struct ib_mad_reg_req {
u8 mgmt_class;
u8 mgmt_class_version;
DECLARE_BITMAP(method_mask, 128);
};
/**
* ib_mad_reg - Register to send/receive MADs.
* @device - The device to register with.
* @port - The port on the specified device to use.
* @qp_type - Specifies which QP to access. Must be either
* IB_QPT_SMI or IB_QPT_GSI.
* @mad_reg_req - Specifies which unsolicited MADs should be received
* by the caller. This parameter may be NULL if the caller only
* wishes to receive solicited responses.
* @rmpp_version - If set to 1, indicates that the client will send
* and receive MADs that contain the RMPP header for the given version.
* If set to 0, indicates that RMPP is not used by this client.
* @send_handler - The completion callback routine invoked after a send
* request has completed.
* @recv_handler - The completion callback routine invoked for a received
* MAD.
* @context - User specified context associated with the registration.
*/
struct ib_mad_agent *ib_mad_reg(struct ib_device *device,
u8 port,
enum ib_qp_type qp_type,
struct ib_mad_reg_req *mad_reg_req,
u8 rmpp_version,
ib_mad_send_handler send_handler,
ib_mad_recv_handler recv_handler,
void *context);
int ib_mad_dereg(struct ib_mad_agent *mad_agent);
int ib_mad_post_send(struct ib_mad_agent *mad_agent,
struct ib_mad_send_wr *mad_send_wr);
struct ib_mad_agent *ib_mad_qp_redir(struct ib_qp *qp,
u8 rmpp_version,
ib_mad_send_handler send_handler,
ib_mad_recv_handler recv_handler,
void *context);
int ib_mad_process_wc(struct ib_mad_agent *mad_agent,
struct ib_wc *wc);
/**
* ib_free_sg_list - Releases the memory associated with a received MAD.
* @sg_list - The sg-list referencing the data buffers to release.
* @num_sge - The number of entries in the sg-list.
*
* This routine releases the memory referenced by the the entries in the
* scatter-gather list, as well as the @sg_list pointer itself.
*/
int ib_free_sg_list(struct ib_sge *sg_list,
int num_sge);
#endif /* IB_MAD_H */
More information about the general
mailing list