1 |
145 |
lanttu |
/*
|
2 |
|
|
Copyright (c) 2008, The Multicore Association
|
3 |
|
|
All rights reserved.
|
4 |
|
|
|
5 |
|
|
Redistribution and use in source and binary forms, with or without
|
6 |
|
|
modification, are permitted provided that the following conditions are
|
7 |
|
|
met:
|
8 |
|
|
|
9 |
|
|
(1) Redistributions of source code must retain the above copyright
|
10 |
|
|
notice, this list of conditions and the following disclaimer.
|
11 |
|
|
|
12 |
|
|
(2) Redistributions in binary form must reproduce the above copyright
|
13 |
|
|
notice, this list of conditions and the following disclaimer in the
|
14 |
|
|
documentation and/or other materials provided with the distribution.
|
15 |
|
|
|
16 |
|
|
(3) Neither the name of the Multicore Association nor the names of its
|
17 |
|
|
contributors may be used to endorse or promote products derived from
|
18 |
|
|
this software without specific prior written permission.
|
19 |
|
|
|
20 |
|
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
|
21 |
|
|
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
22 |
|
|
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
|
23 |
|
|
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
|
24 |
|
|
OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
|
25 |
|
|
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
|
26 |
|
|
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
|
27 |
|
|
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
28 |
|
|
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
|
29 |
|
|
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
30 |
|
|
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
31 |
|
|
*/
|
32 |
|
|
|
33 |
|
|
#ifndef TRANSPORT_H
|
34 |
|
|
#define TRANSPORT_H
|
35 |
|
|
|
36 |
|
|
#include "mcapi_datatypes.h"
|
37 |
|
|
|
38 |
|
|
/* Error handling philosophy:
|
39 |
|
|
mcapi_status_t is handled at the top level shared code in mcapi.c whenever possible. All
|
40 |
|
|
functions in the mcapi_trans layer that need to return status, should return a boolean
|
41 |
|
|
indicating success or failure. All functions that need to pass back additional info
|
42 |
|
|
(such as filling in a handle) should pass that by reference in a parameter.
|
43 |
|
|
*/
|
44 |
|
|
|
45 |
|
|
extern void mcapi_trans_set_debug_level (int d);
|
46 |
|
|
extern void mcapi_trans_display_state (void* handle);
|
47 |
|
|
|
48 |
|
|
extern mcapi_boolean_t mcapi_trans_get_node_num(mcapi_uint_t* node_num);
|
49 |
|
|
extern mcapi_boolean_t mcapi_trans_set_node_num(mcapi_uint_t node_num);
|
50 |
|
|
|
51 |
|
|
/****************** error checking queries *************************/
|
52 |
|
|
/* checks if the given node is valid */
|
53 |
|
|
extern mcapi_boolean_t mcapi_trans_valid_node(mcapi_uint_t node_num);
|
54 |
|
|
|
55 |
|
|
/* checks to see if the port_num is a valid port_num for this system */
|
56 |
|
|
extern mcapi_boolean_t mcapi_trans_valid_port(mcapi_uint_t port_num);
|
57 |
|
|
|
58 |
|
|
/* checks if an enpoint exists on this node for a given port id */
|
59 |
|
|
extern mcapi_boolean_t mcapi_trans_endpoint_exists (uint32_t port_id);
|
60 |
|
|
|
61 |
|
|
/* checks if the endpoint handle refers to a valid endpoint */
|
62 |
|
|
extern mcapi_boolean_t mcapi_trans_valid_endpoint (mcapi_endpoint_t endpoint);
|
63 |
|
|
extern mcapi_boolean_t mcapi_trans_valid_endpoints (mcapi_endpoint_t endpoint1,
|
64 |
|
|
mcapi_endpoint_t endpoint2);
|
65 |
|
|
|
66 |
|
|
/* checks if the channel is open for a given endpoint */
|
67 |
|
|
extern mcapi_boolean_t mcapi_trans_endpoint_channel_isopen (mcapi_endpoint_t endpoint);
|
68 |
|
|
|
69 |
|
|
/* checks if the channel is open for a given pktchan receive handle */
|
70 |
|
|
extern mcapi_boolean_t mcapi_trans_pktchan_recv_isopen (mcapi_pktchan_recv_hndl_t receive_handle) ;
|
71 |
|
|
|
72 |
|
|
/* checks if the channel is open for a given pktchan send handle */
|
73 |
|
|
extern mcapi_boolean_t mcapi_trans_pktchan_send_isopen (mcapi_pktchan_send_hndl_t send_handle) ;
|
74 |
|
|
|
75 |
|
|
/* checks if the channel is open for a given sclchan receive handle */
|
76 |
|
|
extern mcapi_boolean_t mcapi_trans_sclchan_recv_isopen (mcapi_sclchan_recv_hndl_t receive_handle) ;
|
77 |
|
|
|
78 |
|
|
/* checks if the channel is open for a given sclchan send handle */
|
79 |
|
|
extern mcapi_boolean_t mcapi_trans_sclchan_send_isopen (mcapi_sclchan_send_hndl_t send_handle) ;
|
80 |
|
|
|
81 |
|
|
/* checks if the given endpoint is owned by the given node */
|
82 |
|
|
extern mcapi_boolean_t mcapi_trans_endpoint_isowner (mcapi_endpoint_t endpoint);
|
83 |
|
|
|
84 |
|
|
/* returns the channel type */
|
85 |
|
|
channel_type mcapi_trans_channel_type (mcapi_endpoint_t endpoint);
|
86 |
|
|
|
87 |
|
|
/* checks if the endpoint is connected */
|
88 |
|
|
extern mcapi_boolean_t mcapi_trans_channel_connected (mcapi_endpoint_t endpoint);
|
89 |
|
|
|
90 |
|
|
/* checks if this endpoint can be a receive endpoint ie. has not already
|
91 |
|
|
been connected as a send endpoint */
|
92 |
|
|
extern mcapi_boolean_t mcapi_trans_recv_endpoint (mcapi_endpoint_t endpoint);
|
93 |
|
|
|
94 |
|
|
/* checks if this endpoint can be a send endpoint ie. has not already
|
95 |
|
|
been connected as a receive endpoint */
|
96 |
|
|
extern mcapi_boolean_t mcapi_trans_send_endpoint (mcapi_endpoint_t endpoint);
|
97 |
|
|
|
98 |
|
|
/* checks if this node has already called initialize */
|
99 |
|
|
extern mcapi_boolean_t mcapi_trans_initialized (mcapi_node_t node_id);
|
100 |
|
|
|
101 |
|
|
/* returns the number of endpoints for the calling node */
|
102 |
|
|
extern mcapi_uint32_t mcapi_trans_num_endpoints();
|
103 |
|
|
|
104 |
|
|
/* used by msg_send to check if a given priority level is valid */
|
105 |
|
|
extern mcapi_boolean_t mcapi_trans_valid_priority(mcapi_priority_t priority);
|
106 |
|
|
|
107 |
|
|
/* checks if this endpoint is connected */
|
108 |
|
|
extern mcapi_boolean_t mcapi_trans_connected(mcapi_endpoint_t endpoint);
|
109 |
|
|
|
110 |
|
|
/* checks if the status parameter is valid */
|
111 |
|
|
extern mcapi_boolean_t valid_status_param (mcapi_status_t* mcapi_status);
|
112 |
|
|
|
113 |
|
|
/* checks if the version parameter is valid */
|
114 |
|
|
extern mcapi_boolean_t valid_version_param (mcapi_version_t* mcapi_version);
|
115 |
|
|
|
116 |
|
|
/* checks if the buffer parameter is valid */
|
117 |
|
|
extern mcapi_boolean_t valid_buffer_param (void* buffer);
|
118 |
|
|
|
119 |
|
|
/* checks if the request parameter is valid */
|
120 |
|
|
extern mcapi_boolean_t valid_request_param (mcapi_request_t* request);
|
121 |
|
|
|
122 |
|
|
/* checks if the size parameter is valid */
|
123 |
|
|
extern mcapi_boolean_t valid_size_param (size_t* size);
|
124 |
|
|
|
125 |
|
|
/* checks if the given endpoints have compatible attributes */
|
126 |
|
|
extern mcapi_boolean_t mcapi_trans_compatible_endpoint_attributes
|
127 |
|
|
(mcapi_endpoint_t send_endpoint, mcapi_endpoint_t recv_endpoint);
|
128 |
|
|
|
129 |
|
|
/* checks if the given channel handle is valid */
|
130 |
|
|
extern mcapi_boolean_t mcapi_trans_valid_pktchan_send_handle( mcapi_pktchan_send_hndl_t handle);
|
131 |
|
|
extern mcapi_boolean_t mcapi_trans_valid_pktchan_recv_handle( mcapi_pktchan_recv_hndl_t handle);
|
132 |
|
|
extern mcapi_boolean_t mcapi_trans_valid_sclchan_send_handle( mcapi_sclchan_send_hndl_t handle);
|
133 |
|
|
extern mcapi_boolean_t mcapi_trans_valid_sclchan_recv_handle( mcapi_sclchan_recv_hndl_t handle);
|
134 |
|
|
|
135 |
|
|
|
136 |
|
|
/****************** initialization *************************/
|
137 |
|
|
/* initialize the transport layer */
|
138 |
|
|
extern mcapi_boolean_t mcapi_trans_initialize(mcapi_uint_t node_num);
|
139 |
|
|
|
140 |
|
|
/****************** tear down ******************************/
|
141 |
|
|
extern mcapi_boolean_t mcapi_trans_finalize();
|
142 |
|
|
|
143 |
|
|
/****************** endpoints ******************************/
|
144 |
|
|
/* create endpoint <node_num,port_num> and return it's handle */
|
145 |
|
|
extern mcapi_boolean_t mcapi_trans_create_endpoint(mcapi_endpoint_t *endpoint,
|
146 |
|
|
mcapi_uint_t port_num,
|
147 |
|
|
mcapi_boolean_t anonymous);
|
148 |
|
|
|
149 |
|
|
/* non-blocking get endpoint for the given <node_num,port_num> and set
|
150 |
|
|
endpoint parameter to it's handle */
|
151 |
|
|
extern void mcapi_trans_get_endpoint_i( mcapi_endpoint_t* endpoint, mcapi_uint_t node_num,
|
152 |
|
|
mcapi_uint_t port_num,mcapi_request_t* request,
|
153 |
|
|
mcapi_status_t* mcapi_status);
|
154 |
|
|
|
155 |
|
|
/* blocking get endpoint for the given <node_num,port_num> and return it's handle */
|
156 |
|
|
extern void mcapi_trans_get_endpoint(mcapi_endpoint_t *endpoint,mcapi_uint_t node_num,
|
157 |
|
|
mcapi_uint_t port_num);
|
158 |
|
|
|
159 |
|
|
/* delete the given endpoint */
|
160 |
|
|
extern void mcapi_trans_delete_endpoint( mcapi_endpoint_t endpoint);
|
161 |
|
|
|
162 |
|
|
/* get the attribute for the given endpoint and attribute_num */
|
163 |
|
|
extern void mcapi_trans_get_endpoint_attribute( mcapi_endpoint_t endpoint,
|
164 |
|
|
mcapi_uint_t attribute_num,
|
165 |
|
|
void* attribute, size_t attribute_size);
|
166 |
|
|
|
167 |
|
|
/* set the given attribute on the given endpoint */
|
168 |
|
|
extern void mcapi_trans_set_endpoint_attribute( mcapi_endpoint_t endpoint,
|
169 |
|
|
mcapi_uint_t attribute_num,
|
170 |
|
|
const void* attribute, size_t attribute_size);
|
171 |
|
|
|
172 |
|
|
|
173 |
|
|
/****************** msgs **********************************/
|
174 |
|
|
extern void mcapi_trans_msg_send_i( mcapi_endpoint_t send_endpoint,
|
175 |
|
|
mcapi_endpoint_t receive_endpoint,
|
176 |
|
|
char* buffer, size_t buffer_size,
|
177 |
|
|
mcapi_request_t* request,mcapi_status_t* mcapi_status);
|
178 |
|
|
|
179 |
|
|
extern mcapi_boolean_t mcapi_trans_msg_send( mcapi_endpoint_t send_endpoint,
|
180 |
|
|
mcapi_endpoint_t receive_endpoint,
|
181 |
|
|
char* buffer, size_t buffer_size);
|
182 |
|
|
|
183 |
|
|
extern void mcapi_trans_msg_recv_i( mcapi_endpoint_t receive_endpoint,
|
184 |
|
|
char* buffer, size_t buffer_size,
|
185 |
|
|
mcapi_request_t* request,mcapi_status_t* mcapi_status);
|
186 |
|
|
|
187 |
|
|
extern mcapi_boolean_t mcapi_trans_msg_recv( mcapi_endpoint_t receive_endpoint,
|
188 |
|
|
char* buffer, size_t buffer_size,
|
189 |
|
|
size_t* received_size);
|
190 |
|
|
|
191 |
|
|
extern mcapi_uint_t mcapi_trans_msg_available( mcapi_endpoint_t receive_endoint);
|
192 |
|
|
|
193 |
|
|
/****************** channels general ****************************/
|
194 |
|
|
|
195 |
|
|
/****************** pkt channels ****************************/
|
196 |
|
|
extern void mcapi_trans_connect_pktchan_i( mcapi_endpoint_t send_endpoint,
|
197 |
|
|
mcapi_endpoint_t receive_endpoint,
|
198 |
|
|
mcapi_request_t* request,
|
199 |
|
|
mcapi_status_t* mcapi_status);
|
200 |
|
|
|
201 |
|
|
extern void mcapi_trans_open_pktchan_recv_i( mcapi_pktchan_recv_hndl_t* recv_handle,
|
202 |
|
|
mcapi_endpoint_t receive_endpoint,
|
203 |
|
|
mcapi_request_t* request,
|
204 |
|
|
mcapi_status_t* mcapi_status);
|
205 |
|
|
|
206 |
|
|
extern void mcapi_trans_open_pktchan_send_i( mcapi_pktchan_send_hndl_t* send_handle,
|
207 |
|
|
mcapi_endpoint_t send_endpoint,
|
208 |
|
|
mcapi_request_t* request,
|
209 |
|
|
mcapi_status_t* mcapi_status);
|
210 |
|
|
|
211 |
|
|
extern void mcapi_trans_pktchan_send_i( mcapi_pktchan_send_hndl_t send_handle,
|
212 |
|
|
void* buffer, size_t size,
|
213 |
|
|
mcapi_request_t* request,
|
214 |
|
|
mcapi_status_t* mcapi_status);
|
215 |
|
|
|
216 |
|
|
extern mcapi_boolean_t mcapi_trans_pktchan_send( mcapi_pktchan_send_hndl_t send_handle,
|
217 |
|
|
void* buffer, size_t size);
|
218 |
|
|
|
219 |
|
|
extern void mcapi_trans_pktchan_recv_i( mcapi_pktchan_recv_hndl_t receive_handle,
|
220 |
|
|
void** buffer, mcapi_request_t* request,
|
221 |
|
|
mcapi_status_t* mcapi_status);
|
222 |
|
|
|
223 |
|
|
extern mcapi_boolean_t mcapi_trans_pktchan_recv( mcapi_pktchan_recv_hndl_t receive_handle,
|
224 |
|
|
void** buffer, size_t* received_size);
|
225 |
|
|
|
226 |
|
|
extern mcapi_uint_t mcapi_trans_pktchan_available( mcapi_pktchan_recv_hndl_t receive_handle);
|
227 |
|
|
|
228 |
|
|
extern mcapi_boolean_t mcapi_trans_pktchan_free( void* buffer);
|
229 |
|
|
|
230 |
|
|
extern void mcapi_trans_pktchan_recv_close_i( mcapi_pktchan_recv_hndl_t receive_handle,
|
231 |
|
|
mcapi_request_t* request,
|
232 |
|
|
mcapi_status_t* mcapi_status);
|
233 |
|
|
|
234 |
|
|
extern void mcapi_trans_pktchan_send_close_i( mcapi_pktchan_send_hndl_t send_handle,
|
235 |
|
|
mcapi_request_t* request,
|
236 |
|
|
mcapi_status_t* mcapi_status);
|
237 |
|
|
|
238 |
|
|
/****************** scalar channels ****************************/
|
239 |
|
|
extern void mcapi_trans_connect_sclchan_i( mcapi_endpoint_t send_endpoint,
|
240 |
|
|
mcapi_endpoint_t receive_endpoint,
|
241 |
|
|
mcapi_request_t* request,
|
242 |
|
|
mcapi_status_t* mcapi_status);
|
243 |
|
|
|
244 |
|
|
extern void mcapi_trans_open_sclchan_recv_i( mcapi_sclchan_recv_hndl_t* recv_handle,
|
245 |
|
|
mcapi_endpoint_t receive_endpoint,
|
246 |
|
|
mcapi_request_t* request,
|
247 |
|
|
mcapi_status_t* mcapi_status);
|
248 |
|
|
|
249 |
|
|
extern void mcapi_trans_open_sclchan_send_i( mcapi_sclchan_send_hndl_t* send_handle,
|
250 |
|
|
mcapi_endpoint_t send_endpoint,
|
251 |
|
|
mcapi_request_t* request,
|
252 |
|
|
mcapi_status_t* mcapi_status);
|
253 |
|
|
|
254 |
|
|
extern mcapi_boolean_t mcapi_trans_sclchan_send(
|
255 |
|
|
mcapi_sclchan_send_hndl_t send_handle, uint64_t dataword, uint32_t size);
|
256 |
|
|
|
257 |
|
|
extern mcapi_boolean_t mcapi_trans_sclchan_recv(
|
258 |
|
|
mcapi_sclchan_recv_hndl_t receive_handle,uint64_t *data,uint32_t exp_size);
|
259 |
|
|
|
260 |
|
|
extern mcapi_uint_t mcapi_trans_sclchan_available_i( mcapi_sclchan_recv_hndl_t receive_handle);
|
261 |
|
|
|
262 |
|
|
extern void mcapi_trans_sclchan_recv_close_i( mcapi_sclchan_recv_hndl_t recv_handle,
|
263 |
|
|
mcapi_request_t* mcapi_request,
|
264 |
|
|
mcapi_status_t* mcapi_status);
|
265 |
|
|
|
266 |
|
|
extern void mcapi_trans_sclchan_send_close_i( mcapi_sclchan_send_hndl_t send_handle,
|
267 |
|
|
mcapi_request_t* mcapi_request,
|
268 |
|
|
mcapi_status_t* mcapi_status);
|
269 |
|
|
|
270 |
|
|
/****************** test,wait & cancel ****************************/
|
271 |
|
|
extern mcapi_boolean_t mcapi_trans_test_i( mcapi_request_t* request, size_t* size,
|
272 |
|
|
mcapi_status_t* mcapi_status);
|
273 |
|
|
|
274 |
|
|
extern mcapi_boolean_t mcapi_trans_wait( mcapi_request_t* request, size_t* size,
|
275 |
|
|
mcapi_status_t* mcapi_status,
|
276 |
|
|
mcapi_timeout_t timeout);
|
277 |
|
|
extern mcapi_boolean_t mcapi_trans_wait_any(size_t number, mcapi_request_t** requests, size_t* size,
|
278 |
|
|
mcapi_status_t* mcapi_status,
|
279 |
|
|
mcapi_timeout_t timeout);
|
280 |
|
|
|
281 |
|
|
extern int mcapi_trans_wait_first( size_t number, mcapi_request_t** requests,
|
282 |
|
|
size_t* size);
|
283 |
|
|
|
284 |
|
|
extern void mcapi_trans_cancel( mcapi_request_t* request,mcapi_status_t* mcapi_status);
|
285 |
|
|
|
286 |
|
|
/****************** stats ****************************/
|
287 |
|
|
extern void mcapi_trans_display_stats (void* handle);
|
288 |
|
|
|
289 |
|
|
#endif
|