forked from intel/psm
-
Notifications
You must be signed in to change notification settings - Fork 0
/
psm_am.h
290 lines (271 loc) · 13 KB
/
psm_am.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
/*
* 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