| 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 */
|
