1 |
145 |
lanttu |
/*
|
2 |
|
|
* Copyright (c) 2010, Mentor Graphics Corporation
|
3 |
|
|
* All rights reserved.
|
4 |
|
|
*
|
5 |
|
|
* Copyright (c) 2011, The Multicore Association All rights reserved.
|
6 |
|
|
*
|
7 |
|
|
* Redistribution and use in source and binary forms, with or without
|
8 |
|
|
* modification, are permitted provided that the following conditions are met:
|
9 |
|
|
*
|
10 |
|
|
* 1. Redistributions of source code must retain the above copyright notice,
|
11 |
|
|
* this list of conditions and the following disclaimer.
|
12 |
|
|
* 2. Redistributions in binary form must reproduce the above copyright notice,
|
13 |
|
|
* this list of conditions and the following disclaimer in the documentation
|
14 |
|
|
* and/or other materials provided with the distribution.
|
15 |
|
|
* 3. Neither the name of the <ORGANIZATION> nor the names of its contributors
|
16 |
|
|
* may be used to endorse or promote products derived from this software
|
17 |
|
|
* without specific prior written permission.
|
18 |
|
|
*
|
19 |
|
|
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
20 |
|
|
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
21 |
|
|
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
22 |
|
|
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
|
23 |
|
|
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
24 |
|
|
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
25 |
|
|
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
26 |
|
|
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
27 |
|
|
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
28 |
|
|
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
29 |
|
|
* POSSIBILITY OF SUCH DAMAGE.
|
30 |
|
|
*/
|
31 |
|
|
|
32 |
|
|
#ifndef MCAPI_H
|
33 |
|
|
#define MCAPI_H
|
34 |
|
|
|
35 |
|
|
#include <stddef.h> /* Required for size_t */
|
36 |
|
|
#include "mca.h"
|
37 |
|
|
|
38 |
|
|
#ifdef __cplusplus
|
39 |
|
|
extern "C" {
|
40 |
|
|
#endif /* __cplusplus */
|
41 |
|
|
|
42 |
|
|
/*
|
43 |
|
|
* MCAPI type definitions
|
44 |
|
|
* (Additional typedefs under the attribute and initialization sections below)
|
45 |
|
|
*/
|
46 |
|
|
typedef mca_int_t mcapi_int_t;
|
47 |
|
|
typedef mca_int8_t mcapi_int8_t;
|
48 |
|
|
typedef mca_int16_t mcapi_int16_t;
|
49 |
|
|
typedef mca_int32_t mcapi_int32_t;
|
50 |
|
|
typedef mca_int64_t mcapi_int64_t;
|
51 |
|
|
typedef mca_uint_t mcapi_uint_t;
|
52 |
|
|
typedef mca_uint8_t mcapi_uint8_t;
|
53 |
|
|
typedef mca_uint16_t mcapi_uint16_t;
|
54 |
|
|
typedef mca_uint32_t mcapi_uint32_t;
|
55 |
|
|
typedef mca_uint64_t mcapi_uint64_t;
|
56 |
|
|
typedef mca_boolean_t mcapi_boolean_t;
|
57 |
|
|
typedef mca_domain_t mcapi_domain_t;
|
58 |
|
|
typedef mca_node_t mcapi_node_t;
|
59 |
|
|
typedef unsigned int mcapi_port_t; //Changed from int to unsigned int
|
60 |
|
|
typedef mca_status_t mcapi_status_t;
|
61 |
|
|
typedef mca_timeout_t mcapi_timeout_t;
|
62 |
|
|
typedef unsigned int mcapi_priority_t;
|
63 |
|
|
|
64 |
|
|
/*
|
65 |
|
|
* The mcapi_impl_spec.h header file is vendor/implementation specific,
|
66 |
|
|
* and should contain declarations and definitions specific to a particular
|
67 |
|
|
* implementation.
|
68 |
|
|
*
|
69 |
|
|
* This file must be provided by each implementation.
|
70 |
|
|
*
|
71 |
|
|
* It MUST contain type definitions for the following types, which must be either
|
72 |
|
|
* pointers or 32 bit scalars, allowing simple arithmetic equality comparison (a == b).
|
73 |
|
|
* Implementers may which of these type are used.
|
74 |
|
|
*
|
75 |
|
|
* mcapi_endpoint_t; Note: The endpoint identifier must be topology unique.
|
76 |
|
|
* mcapi_pktchan_recv_hndl_t;
|
77 |
|
|
* mcapi_pktchan_send_hndl_t;
|
78 |
|
|
* mcapi_sclchan_send_hndl_t;
|
79 |
|
|
* mcapi_sclchan_recv_hndl_t;
|
80 |
|
|
*
|
81 |
|
|
*
|
82 |
|
|
* It MUST contain the following definition:
|
83 |
|
|
* mcapi_param_t;
|
84 |
|
|
*
|
85 |
|
|
* It MUST contain the following definitions:
|
86 |
|
|
*
|
87 |
|
|
* Number of MCAPI reserved ports, starting at port 0. Reserved ports can be used for implementation specific purposes.
|
88 |
|
|
*
|
89 |
|
|
* MCAPI_NUM_RESERVED_PORTS 1 Number of reserved ports starting at port 0
|
90 |
|
|
*
|
91 |
|
|
*
|
92 |
|
|
* Implementation defined MCAPI MIN and MAX values.
|
93 |
|
|
*
|
94 |
|
|
* Implementations may parameterize implementation specific max values,
|
95 |
|
|
* smaller that the MCAPI max values. Implementations must specify what
|
96 |
|
|
* those smaller values are and how they are set.
|
97 |
|
|
*
|
98 |
|
|
* MCAPI_MAX_DOMAIN Maximum value for domain
|
99 |
|
|
* MCAPI_MAX_NODE Maximum value for node
|
100 |
|
|
* MCAPI_MAX_PORT Maximum value for port
|
101 |
|
|
* MCAPI_MAX_MESSAGE_SIZE Maximum message size
|
102 |
|
|
* MCAPI_MAX_PACKET_SIZE Maximum packet size
|
103 |
|
|
*
|
104 |
|
|
* Implementations may parameterize implementation specific priority min value
|
105 |
|
|
* and set the number of reserved ports. Implementations must specify what
|
106 |
|
|
* those values are and how they are set.
|
107 |
|
|
*
|
108 |
|
|
* MCAPI_MIN_PORT Minimum value for port
|
109 |
|
|
* MCAPI_MIN_PRORITY Minimum priority value
|
110 |
|
|
*
|
111 |
|
|
*/
|
112 |
|
|
#include "mcapi_impl_spec.h"
|
113 |
|
|
|
114 |
|
|
typedef int mcapi_version_t; /* XXX remove me */
|
115 |
|
|
|
116 |
|
|
/* The following constants are not implementation defined */
|
117 |
|
|
#define MCAPI_VERSION 2014 /* Version 2.014 (major #
|
118 |
|
|
+ minor # (3-digit)) */
|
119 |
|
|
#define MCAPI_TRUE MCA_TRUE
|
120 |
|
|
#define MCAPI_FALSE MCA_FALSE
|
121 |
|
|
#define MCAPI_NULL MCA_NULL /* MCAPI Zero value */
|
122 |
|
|
#define MCAPI_PORT_ANY (~0) /* Create endpoint using the next available port */
|
123 |
|
|
#define MCAPI_TIMEOUT_INFINITE (~0) /* Wait forever, no timeout */
|
124 |
|
|
#define MCAPI_TIMEOUT_IMMEDIATE 0 /* Return immediately, with success or failure */
|
125 |
|
|
#define MCAPI_NODE_INVALID (~0) /* Return value for invalid node */
|
126 |
|
|
#define MCAPI_DOMAIN_INVALID (~0) /* Return value for invalid domain */
|
127 |
|
|
#define MCAPI_RETURN_VALUE_INVALID (~0) /* Invalid return value */
|
128 |
|
|
#define MCAPI_MAX_PRORITY 0 /* Maximum priority value */
|
129 |
|
|
#define MCAPI_MAX_STATUS_MSG_LEN 32 /* Maximum status code message length */
|
130 |
|
|
|
131 |
|
|
/*
|
132 |
|
|
* MCAPI Status codes
|
133 |
|
|
*/
|
134 |
|
|
enum mcapi_status_codes {
|
135 |
|
|
MCAPI_SUCCESS = 1, // Indicates operation was successful
|
136 |
|
|
MCAPI_PENDING, // Indicates operation is pending without errors
|
137 |
|
|
MCAPI_TIMEOUT, // The operation timed out
|
138 |
|
|
MCAPI_ERR_PARAMETER, // Incorrect parameter
|
139 |
|
|
MCAPI_ERR_DOMAIN_INVALID, // The parameter is not a valid domain
|
140 |
|
|
MCAPI_ERR_NODE_INVALID, // The parameter is not a valid node
|
141 |
|
|
MCAPI_ERR_NODE_INITFAILED, // The MCAPI node could not be initialized
|
142 |
|
|
MCAPI_ERR_NODE_INITIALIZED, // MCAPI node is already initialized
|
143 |
|
|
MCAPI_ERR_NODE_NOTINIT, // The MCAPI node is not initialized
|
144 |
|
|
MCAPI_ERR_NODE_FINALFAILED, // The MCAPI could not be finalized
|
145 |
|
|
MCAPI_ERR_PORT_INVALID, // The parameter is not a valid port
|
146 |
|
|
MCAPI_ERR_ENDP_INVALID, // The parameter is not a valid endpoint descriptor
|
147 |
|
|
MCAPI_ERR_ENDP_EXISTS, // The endpoint is already created
|
148 |
|
|
MCAPI_ERR_ENDP_GET_LIMIT, // Endpoint get reference count is to high
|
149 |
|
|
MCAPI_ERR_ENDP_DELETED, // The endpoint has been deleted
|
150 |
|
|
MCAPI_ERR_ENDP_NOTOWNER, // An endpoint can only be deleted by its creator
|
151 |
|
|
MCAPI_ERR_ENDP_REMOTE, // Certain operations are only allowed on the node local endpoints
|
152 |
|
|
MCAPI_ERR_ATTR_INCOMPATIBLE, // Connection of endpoints with incompatible attributes not allowed
|
153 |
|
|
MCAPI_ERR_ATTR_SIZE, // Incorrect attribute size
|
154 |
|
|
MCAPI_ERR_ATTR_NUM, // Incorrect attribute number
|
155 |
|
|
MCAPI_ERR_ATTR_VALUE, // Incorrect attribute vale
|
156 |
|
|
MCAPI_ERR_ATTR_NOTSUPPORTED, // Attribute not supported by the implementation
|
157 |
|
|
MCAPI_ERR_ATTR_READONLY, // Attribute is read only
|
158 |
|
|
MCAPI_ERR_MSG_SIZE, // The message size exceeds the maximum size allowed by the MCAPI implementation
|
159 |
|
|
MCAPI_ERR_MSG_TRUNCATED, // The message size exceeds the buffer size
|
160 |
|
|
MCAPI_ERR_CHAN_OPEN, // A channel is open, certain operations are not allowed
|
161 |
|
|
MCAPI_ERR_CHAN_TYPE, // Attempt to open a packet/scalar channel on an endpoint that has been connected with a different channel type
|
162 |
|
|
MCAPI_ERR_CHAN_DIRECTION, // Attempt to open a send handle on a port that was connected as a receiver, or vice versa
|
163 |
|
|
MCAPI_ERR_CHAN_CONNECTED, // A channel connection has already been established for one or both of the specified endpoints
|
164 |
|
|
MCAPI_ERR_CHAN_OPENPENDING, // An open request is pending
|
165 |
|
|
MCAPI_ERR_CHAN_CLOSEPENDING, // A close request is pending.
|
166 |
|
|
MCAPI_ERR_CHAN_NOTOPEN, // The channel is not open (cannot be closed)
|
167 |
|
|
MCAPI_ERR_CHAN_INVALID, // Argument is not a channel handle
|
168 |
|
|
MCAPI_ERR_PKT_SIZE, // The packet size exceeds the maximum size allowed by the MCAPI implementation
|
169 |
|
|
MCAPI_ERR_TRANSMISSION, // Transmission failure
|
170 |
|
|
MCAPI_ERR_PRIORITY, // Incorrect priority level
|
171 |
|
|
MCAPI_ERR_BUF_INVALID, // Not a valid buffer descriptor
|
172 |
|
|
MCAPI_ERR_MEM_LIMIT, // Out of memory
|
173 |
|
|
MCAPI_ERR_REQUEST_INVALID, // Argument is not a valid request handle
|
174 |
|
|
MCAPI_ERR_REQUEST_LIMIT, // Out of request handles
|
175 |
|
|
MCAPI_ERR_REQUEST_CANCELLED, // The request was already canceled
|
176 |
|
|
MCAPI_ERR_WAIT_PENDING, // A wait is pending
|
177 |
|
|
MCAPI_ERR_GENERAL, // To be used by implementations for error conditions not covered by the other status codes
|
178 |
|
|
MCAPI_STATUSCODE_END // This should always be last
|
179 |
|
|
};
|
180 |
|
|
|
181 |
|
|
void mcapi_cancel(mcapi_request_t *, mcapi_status_t *);
|
182 |
|
|
void mcapi_connect_pktchan_i(mcapi_endpoint_t, mcapi_endpoint_t, mcapi_request_t *,
|
183 |
|
|
mcapi_status_t *);
|
184 |
|
|
void mcapi_connect_sclchan_i(mcapi_endpoint_t, mcapi_endpoint_t, mcapi_request_t *,
|
185 |
|
|
mcapi_status_t *);
|
186 |
|
|
void mcapi_delete_endpoint(mcapi_endpoint_t, mcapi_status_t *);
|
187 |
|
|
void mcapi_finalize(mcapi_status_t *);
|
188 |
|
|
void mcapi_get_endpoint_attribute(mcapi_endpoint_t, mcapi_uint_t, void *, size_t,
|
189 |
|
|
mcapi_status_t *);
|
190 |
|
|
void mcapi_get_endpoint_i(mcapi_node_t, mcapi_port_t, mcapi_endpoint_t *,
|
191 |
|
|
mcapi_request_t *, mcapi_status_t *);
|
192 |
|
|
void mcapi_initialize(mcapi_node_t, mcapi_version_t *, mcapi_status_t *);
|
193 |
|
|
void mcapi_msg_recv_i(mcapi_endpoint_t, void *, size_t, mcapi_request_t *,
|
194 |
|
|
mcapi_status_t *);
|
195 |
|
|
void mcapi_msg_recv(mcapi_endpoint_t, void *, size_t, size_t *, mcapi_status_t *);
|
196 |
|
|
void mcapi_msg_send_i(mcapi_endpoint_t, mcapi_endpoint_t, void *, size_t,
|
197 |
|
|
mcapi_priority_t, mcapi_request_t *, mcapi_status_t *);
|
198 |
|
|
void mcapi_msg_send(mcapi_endpoint_t, mcapi_endpoint_t, void *, size_t,
|
199 |
|
|
mcapi_priority_t, mcapi_status_t *);
|
200 |
|
|
void mcapi_open_pktchan_recv_i(mcapi_pktchan_recv_hndl_t *, mcapi_endpoint_t,
|
201 |
|
|
mcapi_request_t *, mcapi_status_t *);
|
202 |
|
|
void mcapi_open_pktchan_send_i(mcapi_pktchan_send_hndl_t *, mcapi_endpoint_t,
|
203 |
|
|
mcapi_request_t *, mcapi_status_t *);
|
204 |
|
|
void mcapi_open_sclchan_recv_i(mcapi_sclchan_recv_hndl_t *, mcapi_endpoint_t,
|
205 |
|
|
mcapi_request_t *, mcapi_status_t *);
|
206 |
|
|
void mcapi_open_sclchan_send_i(mcapi_sclchan_send_hndl_t *, mcapi_endpoint_t,
|
207 |
|
|
mcapi_request_t *, mcapi_status_t *);
|
208 |
|
|
void mcapi_packetchan_recv_close_i(mcapi_pktchan_recv_hndl_t, mcapi_request_t *,
|
209 |
|
|
mcapi_status_t *);
|
210 |
|
|
void mcapi_pktchan_recv_i(mcapi_pktchan_recv_hndl_t, void **, mcapi_request_t *,
|
211 |
|
|
mcapi_status_t *);
|
212 |
|
|
void mcapi_pktchan_recv(mcapi_pktchan_recv_hndl_t, void **, size_t *, mcapi_status_t *);
|
213 |
|
|
void mcapi_packetchan_send_close_i(mcapi_pktchan_send_hndl_t, mcapi_request_t *,
|
214 |
|
|
mcapi_status_t *);
|
215 |
|
|
void mcapi_pktchan_send_i(mcapi_pktchan_send_hndl_t, void *, size_t,
|
216 |
|
|
mcapi_request_t *, mcapi_status_t *);
|
217 |
|
|
void mcapi_pktchan_send(mcapi_pktchan_send_hndl_t, void *, size_t, mcapi_status_t *);
|
218 |
|
|
void mcapi_sclchan_recv_close_i(mcapi_sclchan_recv_hndl_t, mcapi_request_t *,
|
219 |
|
|
mcapi_status_t *);
|
220 |
|
|
void mcapi_sclchan_send_close_i(mcapi_sclchan_send_hndl_t, mcapi_request_t *,
|
221 |
|
|
mcapi_status_t *);
|
222 |
|
|
void mcapi_sclchan_send_uint16(mcapi_sclchan_send_hndl_t, mcapi_uint16_t,
|
223 |
|
|
mcapi_status_t *);
|
224 |
|
|
void mcapi_sclchan_send_uint32(mcapi_sclchan_send_hndl_t, mcapi_uint32_t,
|
225 |
|
|
mcapi_status_t *);
|
226 |
|
|
void mcapi_sclchan_send_uint64(mcapi_sclchan_send_hndl_t, mcapi_uint64_t,
|
227 |
|
|
mcapi_status_t *);
|
228 |
|
|
void mcapi_sclchan_send_uint8(mcapi_sclchan_send_hndl_t, mcapi_uint8_t,
|
229 |
|
|
mcapi_status_t *);
|
230 |
|
|
void mcapi_set_endpoint_attribute(mcapi_endpoint_t, mcapi_uint_t, void *,
|
231 |
|
|
size_t, mcapi_status_t *);
|
232 |
|
|
|
233 |
|
|
mcapi_endpoint_t mcapi_get_endpoint(mcapi_node_t, mcapi_port_t, mcapi_status_t *);
|
234 |
|
|
mcapi_endpoint_t mcapi_create_endpoint(mcapi_port_t, mcapi_status_t *);
|
235 |
|
|
|
236 |
|
|
mcapi_boolean_t mcapi_test(mcapi_request_t *, size_t *, mcapi_status_t *);
|
237 |
|
|
mcapi_boolean_t mcapi_wait(mcapi_request_t *, size_t *, mcapi_status_t *,
|
238 |
|
|
mcapi_timeout_t);
|
239 |
|
|
|
240 |
|
|
mcapi_node_t mcapi_get_node_id(mcapi_status_t *);
|
241 |
|
|
mcapi_uint_t mcapi_msg_available(mcapi_endpoint_t, mcapi_status_t *);
|
242 |
|
|
mcapi_uint_t mcapi_pktchan_available(mcapi_pktchan_recv_hndl_t, mcapi_status_t *);
|
243 |
|
|
void mcapi_pktchan_free(void *, mcapi_status_t *);
|
244 |
|
|
mcapi_uint_t mcapi_sclchan_available(mcapi_sclchan_recv_hndl_t, mcapi_status_t *);
|
245 |
|
|
|
246 |
|
|
mcapi_uint16_t mcapi_sclchan_recv_uint16(mcapi_sclchan_recv_hndl_t, mcapi_status_t *);
|
247 |
|
|
mcapi_uint32_t mcapi_sclchan_recv_uint32(mcapi_sclchan_recv_hndl_t, mcapi_status_t *);
|
248 |
|
|
mcapi_uint64_t mcapi_sclchan_recv_uint64(mcapi_sclchan_recv_hndl_t, mcapi_status_t *);
|
249 |
|
|
mcapi_uint8_t mcapi_sclchan_recv_uint8(mcapi_sclchan_recv_hndl_t, mcapi_status_t *);
|
250 |
|
|
mcapi_int_t mcapi_wait_any(size_t, mcapi_request_t **, size_t *,
|
251 |
|
|
mcapi_timeout_t, mcapi_status_t *);
|
252 |
|
|
|
253 |
|
|
#ifdef __cplusplus
|
254 |
|
|
}
|
255 |
|
|
#endif /* _cplusplus */
|
256 |
|
|
|
257 |
|
|
#endif /* MCAPI_H */
|