psm_am.h

/*
 * Copyright (c) 2006-2012. QLogic Corporation. All rights reserved.
 * Copyright (c) 2003-2006, PathScale, Inc. All rights reserved.
 *
 * 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 from the file
 * COPYING in the main directory of this source tree, or the
 * OpenIB.org BSD license below:
 *
 *     Redistribution and use in source and binary forms, with or
 *     without modification, are permitted provided that the following
 *     conditions are met:
 *
 *      - Redistributions of source code must retain the above
 *        copyright notice, this list of conditions and the following
 *        disclaimer.
 *
 *      - Redistributions in binary form must reproduce the above
 *        copyright notice, this list of conditions and the following
 *        disclaimer in the documentation and/or other materials
 *        provided with the distribution.
 *
 * 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.
 */

#ifndef PSM_AM_H
#define PSM_AM_H

#include <psm.h>

#ifdef __cplusplus
extern "C" {
#endif



/* Datatype for an index number representing an active message handler */
typedef uint32_t psm_handler_t;

/* Datatype for a token for an active message handler.*/
typedef void    *psm_am_token_t;

/* PSM AM flags
 * These flags may be combined using bitwise-or.
 */
#define PSM_AM_FLAG_NONE    0 /* This flag should be used when no other PSM AM flags are needed. */
#define PSM_AM_FLAG_ASYNC   1 /* This flag indicates no need to copy source data. */
#define PSM_AM_FLAG_NOREPLY 2 /* This flag indicates that the handler for this AM request is guaranteed not to generate a reply. */

/* The psm_amarg type represents the type of an AM argument. This is
 *  a 64-bit type and is broken down into four 16-bit fields, two 32-bit
 *  fields or one 64-bit field for the convenience of code using the PSM AM
 *  interface.
 */
typedef
struct psm_amarg { 
    union {
	struct {
	    uint16_t	u16w3;
	    uint16_t	u16w2;
	    uint16_t	u16w1;
	    uint16_t	u16w0;
	};
	struct {
	    uint32_t	u32w1;
	    uint32_t	u32w0;
	};
	uint64_t	u64w0;
	uint64_t	u64;
    };
}
psm_amarg_t;

/* The AM handler function type
 *  
 * psm_am_handler_fm_t is the datatype for an AM handler. PSM AM will call-back
 * into an AM handler using this function prototype. The parameters and result
 * of these handler functions are described here.
 *
 * [in] token This is an opaque token value passed into a handler.
 *                  A request handler may send at most one reply back to the original 
 *                  requestor, and must pass this value as the token parameter
 *                  to the psm_am_reply_short() function. A reply handler is also
 *                  passed a token value, but must not attempt to reply.
 * [in] epaddr The end-point address of the other party in this AM transaction.
 * [in] args A pointer to the arguments provided to this handler.
 * [in] nargs The number of arguments.
 * [in] src A pointer to the data payload provided to this handler.
 * [in] len The length of the data payload in bytes.
 *
 * [returns] 0 The handler should always return a result of 0.
 */
typedef
int (*psm_am_handler_fn_t)(psm_am_token_t token, psm_epaddr_t epaddr,
			   psm_amarg_t *args, int nargs, 
			   void *src, uint32_t len);

/* Type for a completion call-back handler.
 *  
 * A completion handler can be specified to give a call-back on the initiation
 * side that an AM request or reply has completed on the target side. The call-back
 * has a context pointer which is provided along with the call-back function
 * pointer when the initiator generates the request or reply. This approach will
 * typically give higher performance than using an AM request or reply to achieve
 * the same effect, though note that no additional information can be passed
 * from the target side back to the initiator side with the completion handler
 * approach.
 *
 * [in] context A context pointer.
 * [returns] void This handler has no return result.
 */
typedef
void (*psm_am_completion_fn_t)(void *context);

/* Register AM call-back handlers at the specified end-point.
 *
 * This function is used to register an array of handlers, and may be called
 * multiple times to register additonal handlers. The maximum number of handlers
 * that can be registered is limited to the max_handlers value returned by
 * psm_am_get_parameters(). Handlers are associated with a PSM end-point. The
 * handlers are allocated index numbers in the the handler table for that end-point.
 * The allocated index for the handler function in handlers[i] is returned in
 * handlers_idx[i] for i in (0, num_handlers]. These handler index values are
 * used in the psm_am_request_short() and psm_am_reply_short() functions.
 * 
 * [in] ep End-point value
 * [in] handlers Array of handler functions
 * [in] num_handlers Number of handlers (sizes the handlers and handlers_idx arrays)
 * [out] handlers_idx Used to return handler index mapping table
 * 
 * [returns] PSM_OK Indicates success
 * [returns] PSM_EP_NO_RESOURCES Insufficient slots in the AM handler table
 */
psm_error_t psm_am_register_handlers(psm_ep_t ep, 
				     const psm_am_handler_fn_t *handlers, 
				     int num_handlers, int *handlers_idx);

/* Generate an AM request.
 *
 * This function generates an AM request causing an AM handler function to be
 * called in the PSM process associated with the specified end-point address.
 * The number of arguments is limited to max_nargs and the payload length in bytes
 * to max_request_short returned by the psm_am_get_parameters() function.
 * If arguments are not required, set the number of arguments to 0 and the argument
 * pointer will not be dereferenced. If payload is not required, set the payload size
 * to 0 and the payload pointer will not be dereferenced.
 *
 * Optionally a completion function and completion context pointer can be provided,
 * and a local call-back will be made to that function passing in that context
 * pointer once remote execution of the handler has completed. If the completion
 * call-back is not required, the handler should be specified as NULL and the
 * pointer value will not be used.
 * 
 * The allowed flags are any combination of the following combined with bitwise-or:
 *   PSM_AM_FLAG_NONE    - No flags
 *   PSM_AM_FLAG_ASYNC   - Indicates no need to copy source data
 *   PSM_AM_FLAG_NOREPLY - The handler for this AM request is guaranteed not to generate a reply
 *
 * The PSM AM implementation will not dereference the args pointer after return from
 * this function. If PSM_AM_FLAG_ASYNC is not provided, the PSM AM implementation will
 * not dereference the src pointer after return from this function. This may require the
 * implementation to take a copy of the payload if the request cannot be issued immediately.
 * However, if PSM_AM_FLAG_ASYNC is provided then a copy will not be taken and the PSM AM
 * implementation retains ownership of the payload src memory until the request is locally
 * complete. Local completion can be determined using the completion handler call-back, or
 * through an AM handler associated with an AM reply.
 *
 * The PSM_AM_FLAG_NOREPLY flag indicates ahead of time to the AM handler that a reply will
 * not be generated. Use of this flag is optional, but it may enable a performance optimization
 * in this case by indicating that reply state is not required.
 *
 * [in] epaddr End-point address to run handler on
 * [in] handler Index of handler to run
 * [in] args Array of arguments to be provided to the handler
 * [in] nargs Number of arguments to be provided to the handler
 * [in] src Pointer to the payload to be delivered to the handler
 * [in] len Length of the payload in bytes
 * [in] flags These are PSM AM flags and may be combined together with bitwise-or
 * [in] completion_fn The completion function to called locally when remote handler is complete
 * [in] completion_ctxt User-provided context pointer to be passed to the completion handler
 * 
 * [returns] PSM_OK indicates success.
 */
psm_error_t
psm_am_request_short(psm_epaddr_t epaddr, psm_handler_t handler, 
		     psm_amarg_t *args, int nargs, void *src, size_t len,
		     int flags, psm_am_completion_fn_t completion_fn,
		     void *completion_ctxt);

/* Generate an AM reply.
 *
 * This function may only be called from an AM handler called due to an AM request.
 * If the AM request uses the PSM_AM_FLAG_NOREPLY flag, the AM handler must not
 * call this function. Otherwise, the AM request handler may call psm_am_reply_short() 
 * at most once, and must pass in the token value that it received in its own handler 
 * call-back. 
 *
 * This function generates an AM reply causing an AM handler function to be
 * called in the PSM process associated with the specified end-point address.
 * The number of arguments is limited to max_nargs and the payload length in bytes
 * to max_reply_short returned by the psm_am_get_parameters() function.
 * If arguments are not required, set the number of arguments to 0 and the argument
 * pointer will not be dereferenced. If payload is not required, set the payload size
 * to 0 and the payload pointer will not be dereferenced.
 *
 * Optionally a completion function and completion context pointer can be provided,
 * and a local call-back will be made to that function passing in that context
 * pointer once remote execution of the handler has completed. If the completion
 * call-back is not required, the handler should be specified as NULL and the
 * pointer value will not be used.
 * 
 * The allowed flags are any combination of the following combined with bitwise-or:
 *   PSM_AM_FLAG_NONE    - No flags
 *   PSM_AM_FLAG_ASYNC   - Indicates no need to copy source data
 *
 * The PSM AM implementation will not dereference the args pointer after return from
 * this function. If PSM_AM_FLAG_ASYNC is not provided, the PSM AM implementation will
 * not dereference the src pointer after return from this function. This may require the
 * implementation to take a copy of the payload if the reply cannot be issued immediately.
 * However, if PSM_AM_FLAG_ASYNC is provided then a copy will not be taken and the PSM AM
 * implementation retains ownership of the payload src memory until the reply is locally
 * complete. Local completion can be determined using the completion handler call-back.
 *
 * [in] token Token value provided to the AM handler that is generating the reply.
 * [in] handler Index of handler to run
 * [in] args Array of arguments to be provided to the handler
 * [in] nargs Number of arguments to be provided to the handler
 * [in] src Pointer to the payload to be delivered to the handler
 * [in] len Length of the payload in bytes
 * [in] flags These are PSM AM flags and may be combined together with bitwise-or
 * [in] completion_fn The completion function to called locally when remote handler is complete
 * [in] completion_ctxt User-provided context pointer to be passed to the completion handler
 * 
 * [returns] PSM_OK indicates success.
 */
psm_error_t
psm_am_reply_short(psm_am_token_t token, psm_handler_t handler, 
		   psm_amarg_t *args, int nargs, void *src, size_t len, 
		   int flags, psm_am_completion_fn_t completion_fn,
		   void *completion_ctxt);

/* AM parameters
 *
 * This structure is used to return PSM AM implementation-specific parameter
 * values back to the caller of the psm_am_get_parameters() function. This
 * API also specifies the minimum values for these parameters that an 
 * implementation must at least provide:
 *   max_handlers >= 64,
 *   max_nargs >= 2,
 *   max_request_short >= 256 and
 *   max_reply_short >= 256.
 */
struct psm_am_parameters {
    uint32_t    max_handlers;		/* Maximum number of handlers that can be registered. */
    uint32_t	max_nargs;		/* Maximum number of arguments to an AM handler. */
    uint32_t	max_request_short;	/* Maximum number of bytes in a request payload. */
    uint32_t	max_reply_short;	/* Maximum number of bytes in a reply payload. */
};

/* Get the AM parameter values
 *
 * This function retrieves the implementation-specific AM parameter values for 
 * the specified end-point.
 *
 * [in] ep The end-point value returned by psm_ep_open().
 * [out] parameters Pointer to the struct where the parameters will be returned.
 * [in] sizeof_parameters_in The size in bytes of the struct provided by the caller.
 * [out] sizeof_parameters_out The size in bytes of the struct returned by PSM.
 *
 * [returns] PSM_OK indicates success.
 */
psm_error_t
psm_am_get_parameters(psm_ep_t ep, struct psm_am_parameters *parameters,
                      size_t sizeof_parameters_in,
		      size_t *sizeof_parameters_out);


#ifdef __cplusplus
}				/* extern "C" */
#endif

#endif