URL https://opencores.org/ocsvn/funbase_ip_library/funbase_ip_library/trunk
Subversion Repositories funbase_ip_library

[/] [funbase_ip_library/] [trunk/] [TUT/] [ip.swp.api/] [mcapi_top/] [1.0/] [src/] [mcapi.c] - Blame information for rev 145

Details | Compare with Previous | View Log

/*
Copyright (c) 2008, The Multicore Association
All rights reserved.
 
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
 
(1) Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
 
(2) 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.
 
(3) Neither the name of the Multicore Association nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
 
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
 
#include <mcapi.h>
#include <mcapi_trans.h>
#include <mcapi_config.h> /* for MCAPI version */
 
#include <string.h> /* for strncpy */
 
 
/* FIXME: (errata B5) anyone can get an endpoint handle and call receive on it.  should
   this be an error?  It seems like only the node that owns the receive
   endpoint should be able to call receive. */
 
 
/* The following 3 functions are useful for debugging but are not part of the spec */
char* mcapi_display_status (mcapi_status_t status) {
 switch (status) {
 case (MCAPI_INCOMPLETE):     return "MCAPI_INCOMPLETE"; break;
 case (MCAPI_SUCCESS):        return "MCAPI_SUCCESS"; break;
 case (MCAPI_ENO_INIT):       return "MCAPI_ENO_INIT"; break;
 case (MCAPI_EMESS_LIMIT):    return "MCAPI_EMESS_LIMIT"; break;
 case (MCAPI_ENO_BUFFER):     return "MCAPI_ENO_BUFFER"; break;
 case (MCAPI_ENO_REQUEST):    return "MCAPI_ENO_REQUEST"; break;
 case (MCAPI_ENO_MEM):        return "MCAPI_ENO_MEM"; break;
 case (MCAPI_ENO_FINAL):      return "MCAPI_ENO_FINAL"; break;
 case (MCAPI_ENODE_NOTINIT):  return "MCAPI_ENODE_NOTINIT"; break;
 case (MCAPI_EEP_NOTALLOWED): return "MCAPI_EEP_NOTALLOWED"; break;
 case (MCAPI_EPORT_NOTVALID): return "MCAPI_EPORT_NOTVALID"; break;
 case (MCAPI_ENODE_NOTVALID): return "MCAPI_ENODE_NOTVALID"; break;
 case (MCAPI_ENOT_OWNER):     return "MCAPI_ENOT_OWNER"; break;
 case (MCAPI_ECHAN_OPEN):     return "MCAPI_ECHAN_OPEN"; break;
 case (MCAPI_ENO_ENDPOINT):   return "MCAPI_ENO_ENDPOINT"; break;
 case (MCAPI_ECONNECTED):     return "MCAPI_ECONNECTED"; break;
 case (MCAPI_EATTR_INCOMP):   return "MCAPI_EATTR_INCOMP"; break;
 case (MCAPI_ECHAN_TYPE):     return "MCAPI_ECHAN_TYPE"; break;
 case (MCAPI_EDIR):           return "MCAPI_EDIR"; break;
 case (MCAPI_ENOT_HANDLE):    return "MCAPI_ENOT_HANDLE"; break;
 case (MCAPI_ENOT_ENDP):      return "MCAPI_ENOT_ENDP"; break;
 case (MCAPI_EPACK_LIMIT):    return "MCAPI_EPACK_LIMIT"; break;
 case (MCAPI_ENOT_VALID_BUF): return "MCAPI_ENOT_VALID_BUF"; break;
 case (MCAPI_ENOT_OPEN):      return "MCAPI_ENOT_OPEN"; break;
 case (MCAPI_EREQ_CANCELED):  return "MCAPI_EREQ_CANCELED"; break;
 case (MCAPI_ENOTREQ_HANDLE): return "MCAPI_ENOTREQ_HANDLE"; break;
 case (MCAPI_EENDP_ISCREATED):return "MCAPI_EENDP_ISCREATED"; break;
 case (MCAPI_EENDP_LIMIT):    return "MCAPI_EENDP_LIMIT"; break;
 case (MCAPI_ENOT_CONNECTED): return "MCAPI_ENOT_CONNECTED"; break;
 case (MCAPI_ESCL_SIZE):      return "MCAPI_ESCL_SIZE"; break;
 case (MCAPI_EPRIO):          return "MCAPI_EPRIO"; break;
 case (MCAPI_INITIALIZED):    return "MCAPI_INITIALIZED"; break;
 case (MCAPI_EPARAM):         return "MCAPI_EPARAM"; break;
 case (MCAPI_ETRUNCATED):     return "MCAPI_ETRUNCATED"; break;
 case (MCAPI_EREQ_TIMEOUT):   return "MCAPI_EREQ_TIMEOUT"; break;
 default : return "UNKNOWN";
 };
}
 
void mcapi_set_debug_level (int d) {
  mcapi_trans_set_debug_level (d);
}
 
void mcapi_display_state (void* handle) {
  mcapi_trans_display_state(handle);
}
 
 
/***********************************************************************
NAME
mcapi_initialize - Initializes the MCAPI implementation.
DESCRIPTION
mcapi_initialize() initializes the MCAPI environment on a given MCAPI node.
It has to be called by each node using MCAPI.  mcapi_version is set to the
to the implementation version number. A node is a process, a thread, or a
processor (or core) with an independent program counter running a piece
of code. In other words, an MCAPI node is an independent thread of
control. An MCAPI node can call mcapi_initialize() once per node, and it
is an error to call mcapi_initialize() multiple times from a given node.
A given MCAPI implementation will specify what is a node (i.e., what
thread of control - process, thread, or other -- is a node)  in that
implementation. A thread and process are just two examples of threads
of control, and there could be other.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error,
*mcapi_status is set to the appropriate error defined below.
ERRORS
MCAPI_ENO_INIT The MCAPI environment could not be initialized.
MCAPI_INITIALIZED The MCAPI environment has already been initialized.
MCAPI_ENODE_NOTVALID The parameter is not a valid node.
MCAPI_EPARAM Incorrect mcapi_status or mcapi_version parameter.
NOTE
SEE ALSO
mcapi_finalize()
************************************************************************/
void mcapi_initialize(
                      MCAPI_IN mcapi_node_t node_id,
                      MCAPI_OUT mcapi_version_t* mcapi_version,
                      MCAPI_OUT mcapi_status_t* mcapi_status)
{
  if (!valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (!valid_version_param(mcapi_version)) {
      *mcapi_status = MCAPI_EPARAM;
    } else {
      (void)strncpy(*mcapi_version,MCAPI_VERSION,sizeof(MCAPI_VERSION));
      if (!mcapi_trans_valid_node(node_id)) {
        *mcapi_status = MCAPI_ENODE_NOTVALID;
      } else if (mcapi_trans_initialized(node_id)) {
        *mcapi_status = MCAPI_INITIALIZED;
      } else if (!mcapi_trans_initialize(node_id)) {
        *mcapi_status = MCAPI_ENO_INIT;
      }
    }
  }
}
 
/***********************************************************************
NAME
mcapi_finalize - Finalizes the MCAPI implementation.
DESCRIPTION
mcapi_finalize() finalizes the MCAPI environment on a given MCAPI node.
It has to be called by each node using MCAPI.  It is an error to call
mcapi_finalize() without first calling mcapi_initialize().  An MCAPI
node can call mcapi_finalize() once for each call to
mcapi_initialize(), but it is an error to call mcapi_finalize()
multiple times from a given node unless mcapi_initialize() has been
called prior to each mcapi_finalize() call.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error,
*mcapi_status is set to the appropriate error defined below.
ERRORS
MCAPI_ENO_FINAL The MCAPI environment could not be finalized.
MCAPI_EPARAM  Incorrect mcapi_status_ parameter.
NOTE
SEE ALSO
   mcapi_initialize()
************************************************************************/
void mcapi_finalize(
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! mcapi_trans_finalize()) {
      *mcapi_status = MCAPI_ENO_FINAL;
    }
  }
}
 
/***********************************************************************
NAME
mcapi_get_node_id - return the node number associated with the local node
DESCRIPTION
Returns the node id associated with the local node.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error,
*mcapi_status is set to the appropriate error defined below.
ERRORS
MCAPI_ENODE_NOTINIT The node is not initialized.
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
SEE ALSO
************************************************************************/
mcapi_uint_t mcapi_get_node_id(
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  mcapi_uint_t node;
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if  (!mcapi_trans_get_node_num(&node)) {
      *mcapi_status = MCAPI_ENODE_NOTINIT;
    }
  }
 
  return node;
}
 
/***********************************************************************
NAME
mcapi_create_endpoint - create an endpoint.
DESCRIPTION
mcapi_create_endpoint() is used to create endpoints, using the node_id
of the local node calling the API function and specific port_id,
returning a reference to a globally unique endpoint which can later be
referenced by name using mcapi_get_endpoint() (see Section 4.2.3).  The
port_id can be set to MCAPI_PORT ANY to request the next available
endpoint on the local node.
MCAPI supports a simple static naming scheme to create endpoints based
on global tuple names. Other nodes can access the created endpoint by
calling mcapi_get_endpoint() and specifying the appropriate node and
port id's. Enpoints can be passed on to other endpoints and an
endpoint created using MCAPI_PORT ANY has to be passed on to other
endpoints by the creator, to facilitate communication.
Static naming allows the programmer to define an MCAPI communication
topology at compile time.  This facilitates simple initialization.
Section 7.1 illustrates an example of initialization and bootstrapping
using static naming. Creating endpoints using MCAPI_PORT ANY provides
a convenient method to create endpoints without having to specify the
port_id.
RETURN VALUE
On success, an endpoint is returned and *mcapi_status is set to
MCAPI_SUCCESS. On error, MCAPI_NULL is returned and *mcapi_status is
set to the appropriate error defined below.
ERRORS
MCAPI_EPORT_NOTVALID The parameter is not a valid port.
MCAPI_EENDP_ISCREATED  The endpoint is already created.
MCAPI_ENODE_NOTINIT The node is not initialized.
MCAPI_EENDP_LIMIT Exceeded maximum number of endpoints allowed.
MCAPI_EEP_NOTALLOWED Endpoints cannot be created on this node.
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
The node number can only be set using the mcapi_intialize() function.
SEE ALSO
   mcapi_initialize()
************************************************************************/
mcapi_endpoint_t mcapi_create_endpoint(
        MCAPI_IN mcapi_port_t port_id,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  mcapi_endpoint_t e;
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (mcapi_trans_endpoint_exists (port_id)) {
      *mcapi_status = MCAPI_EENDP_ISCREATED;
    } else if (mcapi_trans_num_endpoints () == MAX_ENDPOINTS) {
      *mcapi_status = MCAPI_EENDP_LIMIT;
    } else if (!mcapi_trans_valid_port(port_id)) {
      *mcapi_status = MCAPI_EPORT_NOTVALID;
    } else if (!mcapi_trans_create_endpoint(&e,port_id,MCAPI_FALSE))  {
      *mcapi_status = MCAPI_EEP_NOTALLOWED;
    }
  }
  return e;
}
 
 
/***********************************************************************
NAME
mcapi_get_endpoint_i - obtain the endpoint associated with a given tuple.
DESCRIPTION
mcapi_get_endpoint_i() allows other nodes ("third parties") to get the
endpoint identifier for the endpoint associated with a global tuple name
<node_id, port_id>.  This function is non-blocking and will return
immediately.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error,
*mcapi_status is set to the appropriate error defined below.
ERRORS
MCAPI_EPORT_NOTVALID The parameter is not a valid port.
MCAPI_ENODE_NOTVALID The parameter is not a valid node.
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
Use the mcapi_test(), mcapi_wait() and mcapi_wait_any() functions to
query the status of and mcapi_cancel() function to cancel the operation.
SEE ALSO
  mcapi_get_node_id()
************************************************************************/
void mcapi_get_endpoint_i(
                          MCAPI_IN mcapi_node_t node_id,
                          MCAPI_IN mcapi_port_t port_id,
                          MCAPI_OUT mcapi_endpoint_t* endpoint,
                          MCAPI_OUT mcapi_request_t* request,
                          MCAPI_OUT mcapi_status_t* mcapi_status)
{
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! mcapi_trans_valid_node (node_id)){
      *mcapi_status = MCAPI_ENODE_NOTVALID;
    } else if ( ! mcapi_trans_valid_port (port_id)) {
      *mcapi_status = MCAPI_EPORT_NOTVALID;
    }
    mcapi_trans_get_endpoint_i (endpoint,node_id,port_id,request,mcapi_status);
  }
}
 
/***********************************************************************
NAME
mcapi_get_endpoint - obtain the endpoint associated with a given tuple.
DESCRIPTION
mcapi_get_endpoint() allows other nodes ("third parties") to get the
endpoint identifier for the endpoint associated with a global tuple name
<node_id, port_id>.  This function will block until the specified remote
endpoint has been created via the mcapi_create_endpoint() call.
RETURN VALUE
On success, an endpoint is returned and *mcapi_status is set to
MCAPI_SUCCESS. On error, MCAPI_NULL is returned and *mcapi_status is set
to the appropriate error defined below.
ERRORS
MCAPI_EPORT_NOTVALID The parameter is not a valid port.
MCAPI_ENODE_NOTVALID The parameter is not a valid node.
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
SEE ALSO
************************************************************************/
mcapi_endpoint_t mcapi_get_endpoint(
        MCAPI_IN mcapi_node_t node_id,
        MCAPI_IN mcapi_port_t port_id,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  mcapi_endpoint_t e;
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! mcapi_trans_valid_node (node_id)){
      *mcapi_status = MCAPI_ENODE_NOTVALID;
    } else if ( ! mcapi_trans_valid_port (port_id)) {
      *mcapi_status = MCAPI_EPORT_NOTVALID;
    } else {
      mcapi_trans_get_endpoint (&e,node_id,port_id);
    }
  }
 
  return e;
}
 
/***********************************************************************
NAME
mcapi_delete_endpoint - delete an endpoint.
DESCRIPTION
Deletes an MCAPI endpoint. Pending messages are discarded.  If an
endpoint has been connected to a packet or scalar channel, the
appropriate close method must be called before deleting the endpoint.
Delete is a blocking  operation. Since the connection is closed before
deleting the endpoint, the delete method does not require any
cross-process synchronization and is guaranteed to return in a timely
manner (operation will return without having to block on any IPC to any
remote nodes). It is an error to attempt to delete an endpoint that has
not been closed. Only the node that created an endpoint can delete it.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS.  On error,
*mcapi_status is set to the appropriate error defined below.
ERRORS
MCAPI_ENOT_ENDP Argument is not a valid endpoint descriptor.
MCAPI_ECHAN_OPEN A channel is open, deletion is not allowed.
MCAPI_ENOT_OWNER An endpoint can only be deleted by its creator.
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
SEE ALSO
mcapi_create_endpoint()
************************************************************************/
void mcapi_delete_endpoint(
        MCAPI_IN mcapi_endpoint_t endpoint,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if ( ! mcapi_trans_valid_endpoint(endpoint)) {
      *mcapi_status = MCAPI_ENOT_ENDP;
    } else if (!mcapi_trans_endpoint_isowner (endpoint)) {
      *mcapi_status = MCAPI_ENOT_OWNER;
    } else if ( mcapi_trans_endpoint_channel_isopen (endpoint)) {
      *mcapi_status = MCAPI_ECHAN_OPEN;
    } else {
      /* delete the endpoint */
      mcapi_trans_delete_endpoint (endpoint);
    }
  }
}
 
/***********************************************************************
NAME
mcapi_get_endpoint_attribute - get endpoint attributes.
DESCRIPTION
mcapi_get_endpoint_attribute() allows the programmer to query endpoint
attributes related to buffer management or quality of service.
attribute_num indicates which one of the endpoint attributes is being
referenced. attribute points to a structure or scalar to be filled with
the value of the attribute specified by attribute_num.  attribute size
is the size in bytes of the structure or scalar. See Section 3.2 and the
example mcapi.h for a description of attributes.  The
mcapi_get_endpoint_attribute() function returns the requested attribute
value by reference.
It is an error to attempt a connection between endpoints whose attributes
are set in an incompatible way (for now, whether attributes are compatible
or not is implementation defined).  It is also an error to attempt to
change the attributes of endpoints that are connected.
RETURN VALUE
On success, *attribute is filled with the requested attribute and
*mcapi_status is set to MCAPI_SUCCESS.  On error, *mcapi_status is
set to an error code and *attribute is not modified.
ERRORS
MCAPI_ENOT_ENDP Argument is not an endpoint descriptor.
MCAPI_EATTR_NUM Unknown attribute number.
MCAPI_EATTR_SIZE Incorrect attribute size.
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
SEE ALSO
mcapi_set_endpoint_attribute()
************************************************************************/
void mcapi_get_endpoint_attribute(
        MCAPI_IN mcapi_endpoint_t endpoint,
        MCAPI_IN mcapi_uint_t attribute_num,
        MCAPI_OUT void* attribute,
        MCAPI_IN size_t attribute_size,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  /* FIXME: (errata A3) Not implemented */
}
 
/***********************************************************************
NAME
mcapi_set_endpoint_attribute - set endpoint attributes.
DESCRIPTION
mcapi_set_endpoint_attribute() allows the programmer to assign endpoint
attributes related to buffer management or quality of service.
attribute_num indicates which one of the endpoint attributes is being
referenced. attribute points to a structure or scalar to be filled with
the value of the attribute specified by attribute_num.  attribute size is
the size in bytes of the structure or scalar. See Section 3.2 and mcapi.h
for a description of attributes.
It is an error to attempt a connection between endpoints whose attributes
are set in an incompatible way (for now, whether attributes are compatible
or not is implementation defined).  It is also an error to attempt to
change the attributes of endpoints that are connected.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error, *mcapi_status
is set to the appropriate error defined below.
ERRORS
MCAPI_ENOT_ENDP Argument is not an endpoint descriptor.
MCAPI_EATTR_NUM Unknown attribute number.
MCAPI_EATTR_SIZE Incorrect attribute size.
MCAPI_EPARAM Incorrect mcapi_status parameter.
MCAPI_ECONNECTED Attribute changes not allowed on connected endpoints.
MCAPI_EREAD_ONLY Attribute cannot be modified.
NOTE
SEE ALSO
mcapi_get_endpoint_attribute()
4.3     MCAPI Messages
MCAPI Messages facilitate connectionless transfer of data buffers.  The
messaging API provides a "user-specified buffer" communications interface
- the programmer specifies a buffer of data to be sent on the send side,
and the user specifies an empty buffer to be filled with incoming data on
the receive side.  The implementation must be able to transfer messages to
and from any buffer the programmer specifies, although the implementation
may use extra buffering internally to queue up data between the sender
and receiver.
************************************************************************/
void mcapi_set_endpoint_attribute(
        MCAPI_IN mcapi_endpoint_t endpoint,
        MCAPI_IN mcapi_uint_t attribute_num,
        MCAPI_IN const void* attribute,
        MCAPI_IN size_t attribute_size,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  /* FIXME: (errata A3) not implemented */
}
 
 
/***********************************************************************
NAME
mcapi_msg_send_i - sends a (connectionless) message from a send endpoint
to a receive endpoint.
DESCRIPTION
Sends a (connectionless) message from a send endpoint to a receive
endpoint. It is a non-blocking function, and returns immediately.
send_endpoint, is a local endpoint identifying the send endpoint,
receive_endpoint identifies a receive endpoint. buffer is the application
provided buffer, buffer_size is the buffer size in bytes, priority
determines the message priority and request is the identifier used to
determine if the send operation has completed on the sending endpoint
and the buffer can be reused by the application. Furthermore, this
method will abandon the send and return MCAPI_ENO_MEM if the system
cannot allocate enough memory at the send endpoint to queue up the
outgoing message.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error,
*mcapi_status is set to the appropriate error defined below.
ERRORS
MCAPI_ENOT_ENDP Argument is not an endpoint descriptor.
MCAPI_EMESS_LIMIT The message size exceeds the maximum size allowed by the
MCAPI implementation.
MCAPI_ENO_BUFFER No more message buffers available.
MCAPI_ENO_REQUEST No more request handles available.
MCAPI_ENO_MEM  No memory available.
MCAPI_EPRIO Incorrect priority level.
MCAPI_EPARAM Incorrect request or mcapi_status parameter.
NOTE
Use the mcapi_test(), mcapi_wait() and mcapi_wait_any() functions to
query the status of and mcapi_cancel() function to cancel the operation.
SEE ALSO
************************************************************************/
void mcapi_msg_send_i(
        MCAPI_IN mcapi_endpoint_t send_endpoint,
        MCAPI_IN mcapi_endpoint_t receive_endpoint,
        MCAPI_IN void* buffer,
        MCAPI_IN size_t buffer_size,
        MCAPI_IN mcapi_priority_t priority,
        MCAPI_OUT mcapi_request_t* request,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  /* MCAPI_ENO_BUFFER, MCAPI_ENO_REQUEST, and MCAPI_ENO_MEM handled at the transport layer */
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! mcapi_trans_valid_priority (priority)){
      *mcapi_status = MCAPI_EPRIO;
    } else if (!mcapi_trans_valid_endpoints(send_endpoint,receive_endpoint)) {
      *mcapi_status = MCAPI_ENOT_ENDP; /* FIXME (errata A1) */
    } else if (buffer_size > MAX_MSG_SIZE) {
      *mcapi_status = MCAPI_EMESS_LIMIT;
    }
    mcapi_trans_msg_send_i (send_endpoint,receive_endpoint,buffer,buffer_size,request,mcapi_status);
  }
}
 
 
/***********************************************************************
NAME
mcapi_msg_send - sends a (connectionless) message from a send endpoint to
a receive endpoint.
DESCRIPTION
Sends a (connectionless) message from a send endpoint to a receive endpoint.
It is a blocking function, and returns once the buffer can be reused by the
application. send_endpoint is a local endpoint identifying the send endpoint,
receive_endpoint identifies a receive endpoint. buffer is the application
provided buffer and buffer_size is the buffer size in bytes, and priority
determines the message priority
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error, *mcapi_status
is set to the appropriate error defined below. Success means that the entire
buffer has been sent.
ERRORS
MCAPI_ENOT_ENDP Argument is not an endpoint descriptor.
MCAPI_EMESS_LIMIT The message size exceeds the maximum size allowed by the
MCAPI implementation.
MCAPI_ENO_BUFFER No more message buffers available.
MCAPI_EPRIO Incorrect priority level.
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
SEE ALSO
************************************************************************/
void mcapi_msg_send(
        MCAPI_IN mcapi_endpoint_t  send_endpoint,
        MCAPI_IN mcapi_endpoint_t  receive_endpoint,
        MCAPI_IN void* buffer,
        MCAPI_IN size_t buffer_size,
        MCAPI_IN mcapi_priority_t priority,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
 
  /* FIXME: (errata B1) is it an error to send a message to a connected endpoint? */
 
  /* MCAPI_ENO_BUFFER handled at the transport layer */
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! mcapi_trans_valid_priority (priority)) {
      *mcapi_status = MCAPI_EPRIO;
    } else if (!mcapi_trans_valid_endpoints(send_endpoint,receive_endpoint)) {
      *mcapi_status = MCAPI_ENOT_ENDP; /* FIXME (errata A1) */
    } else if (buffer_size > MAX_MSG_SIZE) {
      *mcapi_status = MCAPI_EMESS_LIMIT;
    } else if ( !mcapi_trans_msg_send (send_endpoint,receive_endpoint,buffer,buffer_size)) {
      /* assume couldn't get a buffer */
      *mcapi_status = MCAPI_ENO_BUFFER;
    }
  }
}
 
 
/***********************************************************************
NAME
mcapi_msg_recv_i - receives a (connectionless) message from a receive
endpoint.
DESCRIPTION
Receives a (connectionless) message from a receive endpoint. It is a
non-blocking function, and returns immediately. receive_endpoint is a
local endpoint identifying the receive endpoint. buffer is the
application provided buffer, and buffer_size is the buffer size in bytes.
request is the identifier used to determine if the receive operation has
completed (all the data is in the buffer).
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error, *mcapi_status
is set to the appropriate error defined below.
ERRORS
MCAPI_ENOT_ENDP Argument is not a valid endpoint descriptor.
MCAPI_ETRUNCATED The message size exceeds the buffer_size.
MCAPI_ENO_REQUEST No more request handles available.
MCAPI_EPARAM Incorrect buffer, request and/or mcapi_status parameter.
NOTE
Use the mcapi_test() , mcapi_wait() and mcapi_wait_any() functions to
query the status of and mcapi_cancel() function to cancel the operation.
SEE ALSO
************************************************************************/
void mcapi_msg_recv_i(
        MCAPI_IN mcapi_endpoint_t  receive_endpoint,
        MCAPI_OUT void* buffer,
        MCAPI_IN size_t buffer_size,
        MCAPI_OUT mcapi_request_t* request,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  /* MCAPI_ENO_REQUEST handled at the transport layer */
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! valid_buffer_param(buffer)) {
      *mcapi_status = MCAPI_EPARAM;
    } else   if (! valid_request_param(request)) {
      *mcapi_status = MCAPI_EPARAM;
    } else if (!mcapi_trans_valid_endpoint(receive_endpoint)) {
      *mcapi_status = MCAPI_ENOT_ENDP;
    }
    mcapi_trans_msg_recv_i(receive_endpoint,buffer,buffer_size,request,mcapi_status);
  }
}
 
 
 
/***********************************************************************
NAME
mcapi_msg_recv - receives a (connectionless) message from a receive endpoint.
DESCRIPTION
Receives a (connectionless) message from a receive endpoint. It is a
blocking function, and returns once a message is available and the received
data filled into the buffer. receive_endpoint is a local endpoint identifying
the receive endpoint. buffer is the application provided buffer, and
buffer_size is the buffer size in bytes.  The received_size parameter is
filled with the actual size of the received message.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error, *mcapi_status
is set to the appropriate error defined below.
ERRORS
MCAPI_ENOT_ENDP Argument is not a valid endpoint descriptor.
MCAPI_ETRUNCATED The message size exceeds the buffer_size.
MCAPI_EPARAM Incorrect buffer and/or mcapi_status parameter.
NOTE
SEE ALSO
************************************************************************/
void mcapi_msg_recv(
        MCAPI_IN mcapi_endpoint_t  receive_endpoint,
        MCAPI_OUT void* buffer,
        MCAPI_IN size_t buffer_size,
        MCAPI_OUT size_t* received_size,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  /* FIXME: (errata B1) is it an error to try to receive a message on a connected endpoint?  */
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else  {
    *mcapi_status = MCAPI_SUCCESS;
    if (! valid_buffer_param(buffer)) {
      *mcapi_status = MCAPI_EPARAM;
    } else if (!mcapi_trans_valid_endpoint(receive_endpoint)) {
      *mcapi_status = MCAPI_ENOT_ENDP;
    } else {
      mcapi_trans_msg_recv(receive_endpoint,buffer,buffer_size,received_size);
      if (*received_size > buffer_size) {
        *received_size = buffer_size;
        *mcapi_status = MCAPI_ETRUNCATED;
      }
    }
  }
}
 
 
/***********************************************************************
NAME
mcapi_msg_available - checks if messages are available on a receive
endpoint.
DESCRIPTION
Checks if messages are available on a receive endpoint.  The function
returns in a timely fashion.  The number of "available" incoming messages
is defined as the number of mcapi_msg_recv() operations that are guaranteed
to not block waiting for incoming data. receive_endpoint is a local
identifier for the receive endpoint. The call only checks the availability
of messages and does not de-queue them. mcapi_msg_available() can only be
used  to check availability on endpoints on the node local to the caller.
RETURN VALUE
On success, the number of available messages is returned and *mcapi_status
is set to MCAPI_SUCCESS. On error, MCAPI_NULL is returned and *mcapi_status
is set to the appropriate error defined below.
ERRORS
MCAPI_ENOT_ENDP Argument is not a valid endpoint descriptor.
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
The status code must be checked to distinguish between no messages and an
error condition.
SEE ALSO
4.4     MCAPI Packet Channels
MCAPI packet channels transfer data packets between a pair of connected
endpoints.   A connection between two endpoints is established via a
two-phase process.  First, some node in the system calls
mcapi_connect_pktchan_i() to define a connection between two endpoints.
This function returns immediately.  In the second phase, both sender and
receiver open their end of the channel by invoking
mcapi_open_pktchan_send_i() and mcapi_open_pktchan_recv_i(), respectively.
The connection is synchronized when both the sender and receiver open
functions have completed.  In order to avoid deadlock situations, the
open functions are non-blocking.
This two-phased binding approach has several important benefits.  The
"connect" call can be made by any node in the system, which allows the
programmer to define the entire channel topology in a single piece of
code.  This code could even be auto-generated by some static connection
tool.  This makes it easy to change the channel topology without having
to modify multiple source files.  This approach also allows the sender
and receiver to do their work without any knowledge of what remote nodes
they are connected to.  This allows for better modularity and application
scaling.
Packet channels provide a "system-specified buffer" interface.  The
programmer specifies the address of a buffer of data to be sent on the
send side, but the receiver's recv method returns a buffer of data at an
address chosen by the system.  This is different from the "user-specified
buffer" interface use by MCAPI messaging - with messages the programmer
chooses the buffer in which data is received, and with packet channels
the system chooses the buffer.
************************************************************************/
mcapi_uint_t mcapi_msg_available(
        MCAPI_IN mcapi_endpoint_t receive_endpoint,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  mcapi_uint_t rc = 0;
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if( !mcapi_trans_valid_endpoint(receive_endpoint)) {
      *mcapi_status = MCAPI_ENOT_ENDP;
    } else {
      rc = mcapi_trans_msg_available(receive_endpoint);
    }
  }
  return rc;
}
 
/***********************************************************************
NAME
mcapi_connect_pktchan_i - connects send & receive side endpoints.
DESCRIPTION
Connects a pair of endpoints into a unidirectional FIFO channel.  The
connect operation can be performed by the sender, the receiver, or by a
third party. The connect can happen once at the start of the program, or
dynamically at run time.
Connect is a non-blocking function. Synchronization to ensure the channel
has been created is provided by the open call discussed later.
Attempts to make multiple connections to a single endpoint will be detected
as errors.  The type of channel connected to an endpoint must match the type
of open call invoked by that endpoint; the open function will return an error
if the opened channel type does not match the connected channel type, or if
the attributes of the endpoints are incompatible.
It is an error to attempt a connection between endpoints whose attributes
are set in an incompatible way (for now, whether attributes are compatible
or not is implementation defined).  It is also an error to attempt to change
the attributes of endpoints that are connected.
RETURN VALUE
On success *mcapi_status is set to MCAPI_SUCCESS. On error, *mcapi_status
is set to the appropriate error defined below.
ERRORS
MCAPI_ENOT_ENDP Argument is not a valid endpoint descriptor.
MCAPI_ECONNECTED A channel connection has already been established for
one or both of the specified endpoints.
MCAPI_ENO_REQUEST No more request handles available.
MCAPI_EATTR_INCOMP Connection of endpoints with incompatible attributes
not allowed.
MCAPI_EPARAM Incorrect request or mcapi_status parameter.
NOTE
Use the mcapi_test() , mcapi_wait() and mcapi_wait_any() functions to
query the status and mcapi_cancel() function to cancel the operation.
SEE ALSO
************************************************************************/
void mcapi_connect_pktchan_i(
        MCAPI_IN mcapi_endpoint_t  send_endpoint,
        MCAPI_IN mcapi_endpoint_t  receive_endpoint,
        MCAPI_OUT mcapi_request_t* request,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  /* MCAPI_ENO_REQUEST handled at the transport layer */
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if ( ! mcapi_trans_valid_endpoints(send_endpoint,receive_endpoint)) {
      *mcapi_status = MCAPI_ENOT_ENDP;
    } else if (( mcapi_trans_channel_connected (send_endpoint)) ||
               ( mcapi_trans_channel_connected (receive_endpoint))) {
      *mcapi_status = MCAPI_ECONNECTED;
    } else if (! mcapi_trans_compatible_endpoint_attributes (send_endpoint,receive_endpoint)) {
      *mcapi_status = MCAPI_EATTR_INCOMP;
    }
    mcapi_trans_connect_pktchan_i (send_endpoint,receive_endpoint,request,mcapi_status);
  }
}
 
 
 
/***********************************************************************
NAME
mcapi_open_pktchan_recv_i - Creates a typed, local representation of the
channel. It also provides synchronization for channel creation between
two endpoints. Opens are required on both receive and send endpoints.
DESCRIPTION
Opens the receive end of a packet channel. The corresponding calls are
required on both sides for synchronization to ensure that the channel
has been created. It is a non-blocking function, and the recv_handle is
filled in upon successful completion. No specific ordering of calls
between sender and receiver is required since the call is non-blocking.
receive_endpoint is the endpoint associated with the channel.  The open
call returns a typed, local handle for the connected channel that is
used for channel receive operations.
RETURN VALUE
On success, a valid request is returned by and *mcapi_status is set to
MCAPI_SUCCESS. On error *mcapi_status is set to the appropriate error
defined below.
ERRORS
MCAPI_ENOT_ENDP Argument is not a valid endpoint descriptor.
MCAPI_ENOT_CONNECTED The channel is not connected (cannot be opened).
MCAPI_ECHAN_TYPE Attempt to open a packet channel on an endpoint that
has been connected with a different channel type.
MCAPI_EDIR Attempt to open a send handle on a port that was connected
as a receiver, or vice versa.
MCAPI_EPARAM Incorrect request or mcapi_status parameter.
NOTE
Use the mcapi_test() , mcapi_wait() and mcapi_wait_any() functions to
query the status and mcapi_cancel() function to cancel the operation.
SEE ALSO
************************************************************************/
void mcapi_open_pktchan_recv_i(
        MCAPI_OUT mcapi_pktchan_recv_hndl_t* recv_handle,
        MCAPI_IN mcapi_endpoint_t receive_endpoint,
        MCAPI_OUT mcapi_request_t* request,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  /* FIXME: (errata B2) shouldn't this function also check  MCAPI_ENO_REQUEST, there are several
     non-blocking functions that don't check for this - is that intentional or an
     oversight in the spec? */
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! valid_request_param(request)) {
      *mcapi_status = MCAPI_EPARAM;
    } else if (! mcapi_trans_valid_endpoint(receive_endpoint) ) {
      *mcapi_status = MCAPI_ENOT_ENDP;
    } else if ( mcapi_trans_channel_type (receive_endpoint) == MCAPI_SCL_CHAN) {
      *mcapi_status = MCAPI_ECHAN_TYPE;
    } else if (! mcapi_trans_recv_endpoint (receive_endpoint)) {
      *mcapi_status = MCAPI_EDIR;
    } else if ( !mcapi_trans_connected (receive_endpoint)) {
      *mcapi_status = MCAPI_ENOT_CONNECTED;
    }
    mcapi_trans_open_pktchan_recv_i(recv_handle,receive_endpoint,request,mcapi_status);
  }
}
 
/***********************************************************************
NAME
mcapi_open_pktchan_send_i - Creates a typed, local representation of the
channel. It also provides synchronization for channel creation between two
endpoints. Opens are required on both receive and send endpoints.
DESCRIPTION
Opens the send end of a packet channel. The corresponding calls are
required on both sides for synchronization to ensure that the channel
has been created. It is a non-blocking function, and the send_handle is
filled in upon successful completion. No specific ordering of calls
between sender and receiver is required since the call is non-blocking.
send_endpoint is the endpoint associated with the channel.  The open call
returns a typed, local handle for the connected endpoint that is used by
channel send operations.
RETURN VALUE
On success, a valid request is returned and *mcapi_status is set to
MCAPI_SUCCESS. On error, *mcapi_status is set to the appropriate error
defined below.
ERRORS
MCAPI_ENOT_ENDP Argument is not a valid endpoint descriptor.
MCAPI_ECHAN_TYPE Attempt to open a packet channel on an endpoint that has
been connected with a different channel type.
MCAPI_EDIR Attempt to open a send handle on a port that was connected
as a receiver, or vice versa.
MCAPI_EPARAM Incorrect request or mcapi_status parameter.
NOTE
Use the mcapi_test() , mcapi_wait() and mcapi_wait_any() functions to
query the status and mcapi_cancel() function to cancel the operation.
SEE ALSO
************************************************************************/
void mcapi_open_pktchan_send_i(
        MCAPI_OUT mcapi_pktchan_send_hndl_t* send_handle,
        MCAPI_IN mcapi_endpoint_t  send_endpoint,
        MCAPI_OUT mcapi_request_t* request,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  /* FIXME: (errata B2) shouldn't this function also check  MCAPI_ENO_REQUEST? */
  /* FIXME: (errata B4) shouldn't this function also check MCAPI_ENOT_CONNECTED?  I do, but it's not in the spec */
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! valid_request_param(request)) {
      *mcapi_status = MCAPI_EPARAM;
    } else if (! mcapi_trans_valid_endpoint(send_endpoint) ) {
      *mcapi_status = MCAPI_ENOT_ENDP;
    } else if ( mcapi_trans_channel_type (send_endpoint) == MCAPI_SCL_CHAN){
      *mcapi_status = MCAPI_ECHAN_TYPE;
    } else if (! mcapi_trans_send_endpoint (send_endpoint)) {
      *mcapi_status = MCAPI_EDIR;
    } else if ( !mcapi_trans_connected (send_endpoint)) {
        // TODO: the status is not updated before this?
//      *mcapi_status = MCAPI_ENOT_CONNECTED;
    }
    mcapi_trans_open_pktchan_send_i(send_handle,send_endpoint,request,mcapi_status);
  }
}
 
/***********************************************************************
NAME
mcapi_pktchan_send_i - sends a (connected) packet on a channel.
DESCRIPTION
Sends a packet on a connected channel. It is a non-blocking function,
and returns immediately. buffer is the application provided buffer and
size is the buffer size. request is the identifier used to determine if
the send operation has completed on the sending endpoint and the buffer
can be reused. While this method returns immediately, data transfer will
not complete until there is sufficient free space in the channels receive
buffer. A subsequent call to mcapi_wait() will block until space becomes
available at the receiver, the send operation has completed, and the send
buffer is available for reuse. Furthermore, this method will abandon the
send and return MCAPI_ENO_MEM if the system cannot allocate enough
memory at the send endpoint to queue up the outgoing packet.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error,
*mcapi_status is set to the appropriate error defined below.
ERRORS
MCAPI_ENOT_HANDLE Argument is not a channel handle.
MCAPI_EPACK_LIMIT The packet size exceeds the maximum size
allowed by the MCAPI implementation.
MCAPI_ENO_BUFFER No more packet buffers available.
MCAPI_ENO_REQUEST No more request handles available.
MCAPI_ENO_MEM  No memory available.
MCAPI_EPARAM Incorrect request or mcapi_status parameter.
NOTE
Use the mcapi_test() , mcapi_wait() and mcapi_wait_any()
functions to query the status and mcapi_cancel() function to cancel the
operation.
SEE ALSO
************************************************************************/
void mcapi_pktchan_send_i(
        MCAPI_IN mcapi_pktchan_send_hndl_t send_handle,
        MCAPI_IN void* buffer,
        MCAPI_IN size_t size,
        MCAPI_OUT mcapi_request_t* request,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  /* MCAPI_ENO_BUFFER, MCAPI_ENO_REQUEST and MCAPI_ENO_MEM handled at the transport layer */
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! valid_request_param(request)) {
      *mcapi_status = MCAPI_EPARAM;
    } else if (! mcapi_trans_valid_pktchan_send_handle(send_handle) ) {
      *mcapi_status = MCAPI_ENOT_HANDLE;
    } else if ( size > MAX_PKT_SIZE) {
      *mcapi_status = MCAPI_EPACK_LIMIT;
    }
    mcapi_trans_pktchan_send_i(send_handle,buffer,size,request,mcapi_status);
  }
}
 
/***********************************************************************
NAME
mcapi_pktchan_send - sends a (connected) packet on a channel.
DESCRIPTION
Sends a packet on a connected channel.  It is a blocking function, and
returns once the buffer can be reused.  send_handle is the efficient local
send handle which represents the send endpoint associated with the channel.
buffer is the application provided buffer and size is the buffer size.  Since
channels behave like FIFPs, this method will block if there is no free space
in the channel's receive buffer.  When sufficient space becomes available
(due to receive calls), the funciton will complete.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error,
*mcapi_status is set to the appropriate error defined below.
ERRORS
MCAPI_ENOT_HANDLE Argument is not a channel handle.
MCAPI_EPACK_LIMIT The packet size exceeds the maximum size
allowed by the MCAPI implementation.
MCAPI_ENO_BUFFER No more packet buffers available.
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
SEE ALSO
************************************************************************/
void mcapi_pktchan_send(
        MCAPI_IN mcapi_pktchan_send_hndl_t send_handle,
        MCAPI_IN void* buffer,
        MCAPI_IN size_t size,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! mcapi_trans_valid_pktchan_send_handle(send_handle) ) {
      *mcapi_status = MCAPI_ENOT_HANDLE;
    } else if ( size > MAX_PKT_SIZE) {
      *mcapi_status = MCAPI_EPACK_LIMIT;
    } else  {
      if (!mcapi_trans_pktchan_send (send_handle,buffer,size)) {
        *mcapi_status = MCAPI_ENO_BUFFER;
      }
    }
  }
}
 
 
/***********************************************************************
NAME
mcapi_pktchan_recv_i - receives a (connected) packet on a channel.
DESCRIPTION
Receives a packet on a connected channel. It is a non-blocking function,
and returns immediately. receive_handle is the receive endpoint.  At some
point in the future, when the receive operation completes, the buffer
parameter is filled with the address of a system-supplied buffer containing
the received packet.  After the receive request has completed and the
application is finished with buffer, buffer should be returned to the system
by calling mcapi_pktchan_free(). request is the identifier used to determine
if the receive operation has completed and buffer is ready for use; the
mcapi_test() , mcapi_wait() or mcapi_wait_any() function will return the
actual size of the received packet.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error, *mcapi_status
is set to the appropriate error defined below.
ERRORS
MCAPI_ENOT_HANDLE Argument is not a channel handle.
MCAPI_EPACKLIMIT The packet size exceeds the maximum size allowed by the
MCAPI implementation.
MCAPI_ENO_BUFFER No more packet buffers available.
MCAPI_ENO_REQUEST No more request handles available.
MCAPI_EPARAM Incorrect buffer, request and/or mcapi_status parameter.
NOTE
Use the mcapi_test() , mcapi_wait() and mcapi_wait_any() functions to
query the status of and mcapi_cancel() function to cancel the operation.
SEE ALSO
************************************************************************/
void mcapi_pktchan_recv_i(
        MCAPI_IN mcapi_pktchan_recv_hndl_t receive_handle,
        MCAPI_OUT void** buffer,
        MCAPI_OUT mcapi_request_t* request,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  /* MCAPI_EPACKLIMIT, MCAPI_ENO_BUFFER, and MCAPI_ENO_REQUEST are handled at the transport layer */
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! valid_request_param(request)) {
      *mcapi_status = MCAPI_EPARAM;
    } else   if (! valid_buffer_param(buffer)) {
      *mcapi_status = MCAPI_EPARAM;
    } else if (! mcapi_trans_valid_pktchan_recv_handle(receive_handle) ) {
      *mcapi_status = MCAPI_ENOT_HANDLE;
    }
    mcapi_trans_pktchan_recv_i (receive_handle,buffer,request,mcapi_status);
  }
}
 
/***********************************************************************
NAME
mcapi_pktchan_recv - receives a data packet on a (connected) channel.
DESCRIPTION
Receives a packet on a connected channel. It is a blocking function, and
returns when the data has been written to the buffer. receive_handle is
the efficient local representation of the receive endpoint associated with
the channel.  buffer is filled with a pointer to the system-supplied
receive buffer and received_size is filled with the size of the packet in
that buffer.  When the application finishes with buffer, it must return
it to the system by calling mcapi_pktchan_free().
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error,
*mcapi_status is set to the appropriate error defined below.
ERRORS
MCAPI_ENOT_HANDLE Argument is not a channel handle.
MCAPI_EPACKLIMIT The package size exceeds the maximum size allowed by
the MCAPI implementation.
MCAPI_ENO_BUFFER No more packet buffers available.
MCAPI_EPARAM Incorrect buffer and/or mcapi_status parameter.
NOTE
SEE ALSO
************************************************************************/
void mcapi_pktchan_recv(
        MCAPI_IN mcapi_pktchan_recv_hndl_t receive_handle,
        MCAPI_OUT void** buffer,
        MCAPI_OUT size_t* received_size,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! valid_buffer_param(buffer)) {
      *mcapi_status = MCAPI_EPARAM;
    } else if (! mcapi_trans_valid_pktchan_recv_handle(receive_handle) ) {
      *mcapi_status = MCAPI_ENOT_HANDLE;
    } else  {
      if (mcapi_trans_pktchan_recv (receive_handle,buffer,received_size)) {
        if ( *received_size > MAX_PKT_SIZE) {
          *mcapi_status = MCAPI_EPACK_LIMIT;
        }
      } else {
        *mcapi_status = MCAPI_ENO_BUFFER;
      }
    }
  }
}
 
/***********************************************************************
NAME
mcapi_pktchan_available - checks if packets are available on a receive
endpoint.
DESCRIPTION
Checks if packets are available on a receive endpoint.   This function
returns in a timely fashion.  The number of available packets is defined
as the number of receive operations that could be performed without
blocking to wait for incoming data.  receive_handle is the efficient
local handle for the packet channel. The call only checks the
availability of messages and does not de-queue them.
RETURN VALUE
On success, the number of available packets are returned and *mcapi_status
is set to MCAPI_SUCCESS. On error, MCAPI_NULL is returned and *mcapi_status
is set to the appropriate error defined below.
ERRORS
MCAPI_ENOT_HANDLE Argument is not a channel handle.
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
The status code must be checked to distinguish between no messages and
an error condition.
SEE ALSO
************************************************************************/
mcapi_uint_t mcapi_pktchan_available(
        MCAPI_IN mcapi_pktchan_recv_hndl_t receive_handle,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  int num = 0;
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! mcapi_trans_valid_pktchan_recv_handle(receive_handle) ) {
      *mcapi_status = MCAPI_ENOT_HANDLE;
    } else {
      num = mcapi_trans_pktchan_available(receive_handle);
    }
  }
  return num;
}
 
/***********************************************************************
NAME
mcapi_pktchan_free - releases a packet buffer obtained from a
mcapi_pktchan_recv() call.
DESCRIPTION
When a user is finished with a packet buffer obtained from
mcapi_pktchan_recv_i() or mcapi_pktchan_recv(), they should invoke this
function to return the buffer to the system.  Buffers can be freed in any
order. This function is guaranteed to return in a timely fashion.
RETURN VALUE
On success *mcapi_status is set to MCAPI_SUCCESS. On error, *mcapi_status
is set to the appropriate error defined below.
ERRORS
MCAPI_ENOT_VALID_BUF Argument is not a valid buffer descriptor.
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
SEE ALSO
   mcapi_pktchan_recv(),    mcapi_pktchan_recv_i()
************************************************************************/
void mcapi_pktchan_free(
        MCAPI_IN void* buffer,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (!mcapi_trans_pktchan_free (buffer)) {
      *mcapi_status = MCAPI_ENOT_VALID_BUF;
    }
  }
}
 
 
/***********************************************************************
NAME
mcapi_packetchan_recv_close_i - closes channel on a receive endpoint.
DESCRIPTION
Closes the receive side of a channel. The sender makes the send-side
call and the receiver makes the receive-side call. The corresponding
calls are required on both sides to ensure that the channel has been
properly closed. It is a non-blocking function, and returns immediately.
receive_handle is the receive endpoint identifier. All pending packets
are discarded, and any attempt to send more packets will give an error.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error
*mcapi_status is set to the appropriate error defined below.
ERRORS
MCAPI_ENOT_HANDLE Argument is not a channel handle.
MCAPI_ENOT_OPEN The endpoint is not open.
MCAPI_EPARAM Incorrect request or mcapi_status parameter.
NOTE
Use the mcapi_test() , mcapi_wait() and mcapi_wait_any() functions to
query the status of and mcapi_cancel() function to cancel the operation.
SEE ALSO
************************************************************************/
void mcapi_pktchan_recv_close_i(
        MCAPI_IN mcapi_pktchan_recv_hndl_t receive_handle,
        MCAPI_OUT mcapi_request_t* request,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! valid_request_param(request)) {
      *mcapi_status = MCAPI_EPARAM;
    } else if (! mcapi_trans_valid_pktchan_recv_handle(receive_handle) ) {
      *mcapi_status = MCAPI_ENOT_HANDLE;
    } else if (! mcapi_trans_pktchan_recv_isopen (receive_handle)) {
      *mcapi_status = MCAPI_ENOT_OPEN;
    }
    mcapi_trans_pktchan_recv_close_i (receive_handle,request,mcapi_status);
  }
}
 
 
/***********************************************************************
NAME
mcapi_pktchan_send_close_i - closes channel on a send endpoint.
DESCRIPTION
Closes the send side of a channel. The sender makes the send-side call
and the receiver makes the receive-side call. The corresponding calls
are required on both sides to ensure that the channel has been properly
closed. It is a non-blocking function, and returns immediately.
send_handle is the send endpoint identifier. Pending packets at the
receiver are not discarded.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error *mcapi_status
is set to the appropriate error defined below.
ERRORS
MCAPI_ENOT_HANDLE Argument is not a channel handle.
MCAPI_ENOT_OPEN The endpoint is not open.
MCAPI_EPARAM Incorrect request or mcapi_status parameter.
NOTE
Use the mcapi_test() , mcapi_wait() and mcapi_wait_any() functions to
query the status of and mcapi_cancel() function to cancel the operation.
SEE ALSO
************************************************************************/
void mcapi_pktchan_send_close_i(
        MCAPI_IN mcapi_pktchan_send_hndl_t send_handle,
        MCAPI_OUT mcapi_request_t* request,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! mcapi_trans_valid_pktchan_recv_handle(send_handle) ) {
      *mcapi_status = MCAPI_ENOT_HANDLE;
    } else if (! mcapi_trans_pktchan_send_isopen (send_handle)) {
      *mcapi_status = MCAPI_ENOT_OPEN;
    } if (! valid_request_param(request)) {
      *mcapi_status = MCAPI_EPARAM;
    }
    mcapi_trans_pktchan_send_close_i (send_handle,request,mcapi_status);
  }
}
 
 
/***********************************************************************
NAME
mcapi_connect_sclchan_i - connects a pair of scalar channel endpoints.
DESCRIPTION
Connects a pair of endpoints.  The connect operation can be performed by
the sender, the receiver, or by a third party. The connect can happen
once at the start of the program, or dynamically at run time.
mcapi_connect_sclchan_i() is a non-blocking function. Synchronization
to ensure the channel has been created is provided by the open call
discussed later.
Note that this function behaves like the packetchannel connect call.
Attempts to make multiple connections to a single endpoint will be
detected as errors.  The type of channel connected to an endpoint must
match the type of open call invoked by that endpoint; the open
function will return an error if the opened channel type does not
match the connected channel type, or if the attributes of the endpoints
are incompatible.
It is an error to attempt a connection between endpoints whose
attributes are set in an incompatible way (for now, whether attributes
are compatible or not is implementation defined).  It is also an error
to attempt to change the attributes of endpoints that are connected.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error
*mcapi_status is set to the appropriate error defined below.
ERRORS
MCAPI_ENOT_ENDP Argument is not a valid endpoint descriptor.
MCAPI_ECONNECTED A channel connection has already been established for
one or both of the specified endpoints.
MCAPI_EATTR_INCOMP Connection of endpoints with incompatible attributes
not allowed.
MCAPI_ENO_REQUEST No more request handles available.
MCAPI_EPARAM Incorrect request or mcapi_status parameter.
NOTE
Use the mcapi_test() , mcapi_wait() and mcapi_wait_any() functions to
query the status of and mcapi_cancel() function to cancel the operation.
SEE ALSO
************************************************************************/
void  mcapi_connect_sclchan_i(
        MCAPI_IN mcapi_endpoint_t send_endpoint,
        MCAPI_IN mcapi_endpoint_t receive_endpoint,
        MCAPI_OUT mcapi_request_t* request,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! valid_request_param(request)) {
      *mcapi_status = MCAPI_EPARAM;
    } else if ( ! mcapi_trans_valid_endpoints(send_endpoint,receive_endpoint)) {
      *mcapi_status = MCAPI_ENOT_ENDP;
    } else if (( mcapi_trans_channel_connected (send_endpoint)) ||
               ( mcapi_trans_channel_connected (receive_endpoint))) {
      *mcapi_status = MCAPI_ECONNECTED;
    } else if (! mcapi_trans_compatible_endpoint_attributes (send_endpoint,receive_endpoint)) {
      *mcapi_status = MCAPI_EATTR_INCOMP;
    }
    mcapi_trans_connect_sclchan_i (send_endpoint,receive_endpoint,request,mcapi_status);
  }
}
 
 
/***********************************************************************
NAME
mcapi_open_sclchan_recv_i - Creates a typed, local representation of a
scalar channel.
DESCRIPTION
Opens the receive end of a scalar channel. It also provides
synchronization for channel creation between two endpoints. The
corresponding calls are required on both sides to synchronize the
endpoints. It is a non-blocking function, and the recv_handle is filled
in upon successful completion.  No specific ordering of calls between
sender and receiver is required since the call is non-blocking.
receive_endpoint is the local endpoint identifier. The call returns a
local handle for the connected channel.
RETURN VALUE
On success, a channel handle is returned by reference and *mcapi_status
is set to MCAPI_SUCCESS. On error, *mcapi_status is set to the
appropriate error defined below.
ERRORS
MCAPI_ENOT_ENDP Argument is not an endpoint descriptor.
MCAPI_ENOT_CONNECTED The channel is not connected (cannot be opened).
MCAPI_ECHAN_TYPE Attempt to open a packet channel on an endpoint that
has been connected with a different channel type.
MCAPI_EDIR Attempt to open a send handle on a port that was connected
as a receiver, or vice versa.
MCAPI_EPARAM Incorrect request or mcapi_status parameter.
NOTE
Use the mcapi_test() , mcapi_wait() and mcapi_wait_any() functions to
query the status and mcapi_cancel() function to cancel the operation.
SEE ALSO
************************************************************************/
void mcapi_open_sclchan_recv_i(
        MCAPI_OUT mcapi_sclchan_recv_hndl_t* receive_handle,
        MCAPI_IN mcapi_endpoint_t receive_endpoint,
        MCAPI_OUT mcapi_request_t* request,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  /* FIXME: (errata B2) shouldn't this function also check  MCAPI_ENO_REQUEST? */
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! valid_request_param(request)) {
      *mcapi_status = MCAPI_EPARAM;
    } else if (! mcapi_trans_valid_endpoint(receive_endpoint) ) {
      *mcapi_status = MCAPI_ENOT_ENDP;
    } else if ( mcapi_trans_channel_type (receive_endpoint) == MCAPI_PKT_CHAN) {
      *mcapi_status = MCAPI_ECHAN_TYPE;
    } else if (! mcapi_trans_recv_endpoint (receive_endpoint)) {
      *mcapi_status = MCAPI_EDIR;
    } else if ( !mcapi_trans_connected (receive_endpoint)) {
      *mcapi_status = MCAPI_ENOT_CONNECTED;
    }
    mcapi_trans_open_sclchan_recv_i(receive_handle,receive_endpoint,request,mcapi_status);
  }
}
 
/***********************************************************************
NAME
mcapi_open_sclchan_send_i - Creates a typed, local representation of a
scalar channel.
DESCRIPTION
Opens the send end of a scalar channel. . It also provides
synchronization for channel creation between two endpoints.  The
corresponding calls are required on both sides to synchronize the
endpoints. It is a non-blocking function, and the send_handle is filled
in upon successful completion.   No specific ordering of calls between
sender and receiver is required since the call is non-blocking.
send_endpoint is the local endpoint identifier. The call returns a
local handle for connected channel.
RETURN VALUE
On success, a channel handle is returned by reference and *mcapi_status
is set to MCAPI_SUCCESS. On error, *mcapi_status is set to the appropriate
error defined below.
ERRORS
MCAPI_ENOT_ENDP Argument is not an endpoint descriptor.
MCAPI_ECHAN_TYPE Attempt to open a packet channel on an endpoint that has
been connected with a different channel type.
MCAPI_EDIR Attempt to open a send handle on a port that was connected as
a receiver, or vice versa.
MCAPI_EPARAM Incorrect request or mcapi_status parameter.
NOTE
Use the mcapi_test() , mcapi_wait() and mcapi_wait_any() functions to
query the status and mcapi_cancel() function to cancel the operation.
SEE ALSO
************************************************************************/
void mcapi_open_sclchan_send_i(
        MCAPI_OUT mcapi_sclchan_send_hndl_t* send_handle,
        MCAPI_IN mcapi_endpoint_t send_endpoint,
        MCAPI_OUT mcapi_request_t* request,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! valid_request_param(request)) {
      *mcapi_status = MCAPI_EPARAM;
    } else if (! mcapi_trans_valid_endpoint(send_endpoint) ) {
      *mcapi_status = MCAPI_ENOT_ENDP;
    } else if  (mcapi_trans_channel_type (send_endpoint) == MCAPI_PKT_CHAN){
      *mcapi_status = MCAPI_ECHAN_TYPE;
    } else if (! mcapi_trans_send_endpoint (send_endpoint)) {
      *mcapi_status = MCAPI_EDIR;
    } else if ( !mcapi_trans_connected (send_endpoint)) {
      *mcapi_status = MCAPI_ENOT_CONNECTED;
    }
    /* FIXME:(errata B2) shouldn't this function also check  MCAPI_ENO_REQUEST  */
    /* FIXME: (errata B4) shouldn't this function also check  MCAPI_ENOT_CONNECTED.
       I do, but it's not in the spec */
    mcapi_trans_open_sclchan_send_i(send_handle,send_endpoint,request,mcapi_status);
  }
}
 
/***********************************************************************
NAME
mcapi_sclchan_send_uint64 - sends a (connected) 64-bit scalar on a channel.
DESCRIPTION
Sends a scalar on a connected channel. It is a blocking function, and
returns immediately unless the buffer is full. send_handle is the send
endpoint identifier. dataword is the scalar. Since channels behave like
FIFOs, this method will block if there is no free space in the channel's
receive buffer. When sufficient space becomes available
(due to receive calls), the function will complete.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error *mcapi_status is
set to the appropriate error defined below.  Optionally, implementations may
choose to always set *mcapi_status to MCAPI_SUCCESS for performance reasons.
ERRORS
MCAPI_ENOT_HANDLE Argument is not a channel handle.
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
SEE ALSO
************************************************************************/
void mcapi_sclchan_send_uint64(
        MCAPI_IN mcapi_sclchan_send_hndl_t send_handle,
        MCAPI_IN mcapi_uint64_t dataword,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  /* FIXME: (errata B3) this function needs to check MCAPI_ENO_BUFFER */
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! mcapi_trans_valid_sclchan_send_handle(send_handle) ) {
      *mcapi_status = MCAPI_ENOT_HANDLE;
    }  else if (!mcapi_trans_sclchan_send (send_handle,dataword,8)) {
      *mcapi_status = MCAPI_ENO_BUFFER;  /* MR: added this  */
    }
  }
}
 
 
 
 
/***********************************************************************
NAME
mcapi_sclchan_send_uint32 - sends a (connected) 32-bit scalar on a
channel.
DESCRIPTION
Sends a scalar on a connected channel. It is a blocking function, and
returns immediately unless the buffer is full. send_handle is the send
endpoint identifier. dataword is the scalar. Since channels behave like
FIFOs, this method will block if there is no free space in the channel's
receive buffer. When sufficient space becomes available
(due to receive calls), the function will complete.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error
*mcapi_status is set to the appropriate error defined below.
Optionally, implementations may choose to always set *mcapi_status to
MCAPI_SUCCESS for performance reasons.
ERRORS
MCAPI_ENOT_HANDLE Argument is not a channel handle.
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
SEE ALSO
************************************************************************/
void mcapi_sclchan_send_uint32(
        MCAPI_IN mcapi_sclchan_send_hndl_t send_handle,
        MCAPI_IN mcapi_uint32_t dataword,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  /* FIXME: (errata B3) this function needs to check MCAPI_ENO_BUFFER */
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
#ifdef __TCE__
    uint64_t data64;
    data64.lo = dataword;
 
    if (! mcapi_trans_valid_sclchan_send_handle(send_handle) ) {
      *mcapi_status = MCAPI_ENOT_HANDLE;
    }  else if (!mcapi_trans_sclchan_send (send_handle,data64,4)) {
      *mcapi_status = MCAPI_ENO_BUFFER;
    }
#else
    if (! mcapi_trans_valid_sclchan_send_handle(send_handle) ) {
      *mcapi_status = MCAPI_ENOT_HANDLE;
    }  else if (!mcapi_trans_sclchan_send (send_handle,dataword,4)) {
      *mcapi_status = MCAPI_ENO_BUFFER;
    }
#endif
  }
}
 
/***********************************************************************
NAME
mcapi_sclchan_send_uint16 - sends a (connected) 16-bit scalar on a channel.
DESCRIPTION
Sends a scalar on a connected channel. It is a blocking function, and
returns immediately unless the buffer is full. send_handle is the send
endpoint identifier. dataword is the scalar. Since channels behave like
FIFOs, this method will block if there is no free space in the channel's
receive buffer. When sufficient space becomes available (due to receive
calls), the function will complete.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error *mcapi_status
is set to the appropriate error defined below.  Optionally, implementations
may choose to always set *mcapi_status to MCAPI_SUCCESS for performance
reasons.
ERRORS
MCAPI_ENOT_HANDLE Argument is not a channel handle.
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
SEE ALSO
************************************************************************/
void mcapi_sclchan_send_uint16(
        MCAPI_IN mcapi_sclchan_send_hndl_t send_handle,
        MCAPI_IN mcapi_uint16_t dataword,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  /* FIXME: (errata B3) this function needs to check MCAPI_ENO_BUFFER */
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
 
#ifdef __TCE__
    uint64_t data64;
    data64.lo = dataword;
    if (! mcapi_trans_valid_sclchan_send_handle(send_handle) ) {
      *mcapi_status = MCAPI_ENOT_HANDLE;
    }  else if (!mcapi_trans_sclchan_send (send_handle,data64,2)) {
      *mcapi_status = MCAPI_ENO_BUFFER;
    }
#else
    if (! mcapi_trans_valid_sclchan_send_handle(send_handle) ) {
      *mcapi_status = MCAPI_ENOT_HANDLE;
    }  else if (!mcapi_trans_sclchan_send (send_handle,dataword,2)) {
      *mcapi_status = MCAPI_ENO_BUFFER;
    }
#endif
  }
}
 
 
/***********************************************************************
NAME
mcapi_sclchan_send_uint8 - sends a (connected) 8-bit scalar on a channel.
DESCRIPTION
Sends a scalar on a connected channel. It is a blocking function, and
returns immediately unless the buffer is full. send_handle is the send
endpoint identifier. dataword is the scalar. Since channels behave like
FIFOs, this method will block if there is no free space in the channel's
receive buffer. When sufficient space becomes available (due to receive
calls), the function will complete.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error *mcapi_status
is set to the appropriate error defined below.  Optionally,
implementations may choose to always set *mcapi_status to MCAPI_SUCCESS
for performance reasons.
ERRORS
MCAPI_ENOT_HANDLE Argument is not a channel handle.
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
SEE ALSO
************************************************************************/
void mcapi_sclchan_send_uint8(
        MCAPI_IN mcapi_sclchan_send_hndl_t send_handle,
        MCAPI_IN mcapi_uint8_t dataword,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  /* FIXME: (errata B3) this function needs to check MCAPI_ENO_BUFFER */
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
 
#ifdef __TCE__
    uint64_t data64;
    data64.lo = dataword;
 if (! mcapi_trans_valid_sclchan_send_handle(send_handle) ) {
    *mcapi_status = MCAPI_ENOT_HANDLE;
  }  else if (!mcapi_trans_sclchan_send (send_handle,data64,1)) {
    *mcapi_status = MCAPI_ENO_BUFFER;
  }
#else
 if (! mcapi_trans_valid_sclchan_send_handle(send_handle) ) {
    *mcapi_status = MCAPI_ENOT_HANDLE;
  }  else if (!mcapi_trans_sclchan_send (send_handle,dataword,1)) {
    *mcapi_status = MCAPI_ENO_BUFFER;
  }
#endif
}
}
 
/***********************************************************************
NAME
mcapi_sclchan_recv_uint64 - receives a (connected) 64-bit scalar on a
channel.
DESCRIPTION
Receives a scalar on a connected channel. It is a blocking function,
and returns when a scalar is available. receive_handle is the receive
endpoint identifier.
RETURN VALUE
On success, a value of type uint64_t is returned and *mcapi_status is
set to MCAPI_SUCCESS. On error, the return value is undefined and
*mcapi_status is set to the appropriate error defined below.  Optionally,
implementations may choose to always set *mcapi_status to MCAPI_SUCCESS
for performance reasons.
ERRORS
MCAPI_ENOT_HANDLE Argument is not a channel handle.
MCAPI_EPARAM Incorrect mcapi_status parameter.
MCAPI_ESCL_SIZE Incorrect scalar size.
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
The receive scalar size must match the send size.
SEE ALSO
************************************************************************/
mcapi_uint64_t mcapi_sclchan_recv_uint64(
        MCAPI_IN mcapi_sclchan_recv_hndl_t receive_handle,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  uint32_t exp_size = 8;
#ifdef __TCE__
    uint64_t dataword;
    dataword.lo = 0;
    dataword.hi = 0;
#else
  uint64_t dataword = 0;
#endif
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! mcapi_trans_valid_sclchan_recv_handle(receive_handle) ) {
      *mcapi_status = MCAPI_ENOT_HANDLE;
    }else if (! mcapi_trans_sclchan_recv (receive_handle,&dataword,exp_size)) {
      *mcapi_status = MCAPI_ESCL_SIZE;
    }
  }
  return dataword;
}
 
/***********************************************************************
NAME
mcapi_sclchan_recv_uint32 - receives a 32-bit scalar on a (connected)
channel.
DESCRIPTION
Receives a scalar on a connected channel. It is a blocking function,
and returns when a scalar is available. receive_handle is the receive
endpoint identifier.
RETURN VALUE
On success, a value of type uint32_t is returned and *mcapi_status is
set to MCAPI_SUCCESS. On error, the return value is undefined and
*mcapi_status is set to the appropriate error defined below.  Optionally,
implementations may choose to always set *mcapi_status to MCAPI_SUCCESS
for performance reasons.
ERRORS
MCAPI_ENOT_HANDLE Argument is not a channel handle.
MCAPI_EPARAM Incorrect mcapi_status parameter.
MCAPI_ESCL_SIZE Incorrect scalar size.
 
NOTE
The receive scalar size must match the send size.
SEE ALSO
************************************************************************/
mcapi_uint32_t mcapi_sclchan_recv_uint32(
        MCAPI_IN mcapi_sclchan_recv_hndl_t receive_handle,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  uint32_t exp_size = 4;
#ifdef __TCE__
    uint64_t dataword;
    dataword.lo = 0;
    dataword.hi = 0;
#else
  uint64_t dataword = 0;
#endif
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! mcapi_trans_valid_sclchan_recv_handle(receive_handle) ) {
      *mcapi_status = MCAPI_ENOT_HANDLE;
    } else if (! mcapi_trans_sclchan_recv (receive_handle,&dataword,exp_size)) {
      *mcapi_status = MCAPI_ESCL_SIZE;
    }
  }
#ifdef __TCE__
  return dataword.lo;
#else
  return dataword;
#endif
}
 
 
/***********************************************************************
NAME
mcapi_sclchan_recv_uint16 - receives a 16-bit scalar on a (connected)
channel.
DESCRIPTION
Receives a scalar on a connected channel. It is a blocking function, and
returns when a scalar is available. receive_handle is the receive endpoint
identifier.
RETURN VALUE
On success, a value of type uint16_t is returned and *mcapi_status is
set to MCAPI_SUCCESS. On error, the return value is undefined and
*mcapi_status is set to the appropriate error defined below.  Optionally,
implementations may choose to always set *mcapi_status to MCAPI_SUCCESS
for performance reasons.
ERRORS
MCAPI_ENOT_HANDLE Argument is not a channel handle.
MCAPI_EPARAM Incorrect mcapi_status parameter.
MCAPI_ESCL_SIZE Incorrect scalar size.
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
The receive scalar size must match the send size.
SEE ALSO
************************************************************************/
mcapi_uint16_t mcapi_sclchan_recv_uint16(
        MCAPI_IN mcapi_sclchan_recv_hndl_t receive_handle,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  uint32_t exp_size = 2;
#ifdef __TCE__
    uint64_t dataword;
    dataword.lo = 0;
    dataword.hi = 0;
#else
  uint64_t dataword = 0;
#endif
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! mcapi_trans_valid_sclchan_recv_handle(receive_handle) ) {
      *mcapi_status = MCAPI_ENOT_HANDLE;
    } else if (! mcapi_trans_sclchan_recv (receive_handle,&dataword,exp_size)) {
      *mcapi_status = MCAPI_ESCL_SIZE;
    }
  }
#ifdef __TCE__
  return dataword.lo;
#else
  return dataword;
#endif
}
 
 
/***********************************************************************
NAME
mcapi_sclchan_recv_uint8 - receives a (connected) 8-bit scalar on a
channel.
DESCRIPTION
Receives a scalar on a connected channel. It is a blocking function,
and returns when a scalar is available. receive_handle is the receive
endpoint identifier.
RETURN VALUE
On success, a value of type uint8_t is returned and *mcapi_status is set
to MCAPI_SUCCESS. On error, the return value is undefined and
*mcapi_status is set to the appropriate error defined below.  Optionally,
implementations may choose to always set *mcapi_status to MCAPI_SUCCESS
for performance reasons.
ERRORS
MCAPI_ENOT_HANDLE Argument is not a channel handle.
MCAPI_EPARAM Incorrect mcapi_status parameter.
MCAPI_ESCL_SIZE Incorrect scalar size.
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
The receive scalar size must match the send size.
SEE ALSO
************************************************************************/
mcapi_uint8_t mcapi_sclchan_recv_uint8(
        MCAPI_IN mcapi_sclchan_recv_hndl_t receive_handle,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  uint32_t exp_size = 1;
#ifdef __TCE__
    uint64_t dataword;
    dataword.lo = 0;
    dataword.hi = 0;
#else
  uint64_t dataword = 0;
#endif
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! mcapi_trans_valid_sclchan_recv_handle(receive_handle) ) {
      *mcapi_status = MCAPI_ENOT_HANDLE;
    } else if (! mcapi_trans_sclchan_recv (receive_handle,&dataword,exp_size)) {
      *mcapi_status = MCAPI_ESCL_SIZE;
    }
  }
#ifdef __TCE__
  return dataword.lo;
#else
  return dataword;
#endif
}
 
 
/***********************************************************************
NAME
mcapi_sclchan_available - checks if scalars are available on a receive
 endpoint.
DESCRIPTION
Checks if scalars are available on a receive endpoint. The function returns
immediately. receive_endpoint is the receive endpoint identifier. The call
only checks the availability of messages does not de-queue them.
RETURN VALUE
On success, the number of available scalars are returned and *mcapi_status
is set to MCAPI_SUCCESS. On error, MCAPI_NULL is returned and *mcapi_status
is set to the appropriate error defined below.
ERRORS
MCAPI_ENOT_HANDLE Argument is not a channel handle.
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
The status code must be checked to distinguish between no messages and an
error condition.
SEE ALSO
************************************************************************/
mcapi_uint_t mcapi_sclchan_available (
        MCAPI_IN mcapi_sclchan_recv_hndl_t receive_handle,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  int num = 0;
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! mcapi_trans_valid_sclchan_recv_handle(receive_handle) ) {
      *mcapi_status = MCAPI_ENOT_HANDLE;
    } else {
      num = mcapi_trans_sclchan_available_i(receive_handle);
    }
  }
  return num;
}
 
/***********************************************************************
NAME
mcapi_ sclchan_recv_close_i - closes channel on a receive endpoint.
DESCRIPTION
Closes the receive side of a channel. The corresponding calls are required
on both send and receive sides to ensure that the channel is properly
closed. It is a non-blocking function, and returns immediately.
 receive_handle is the receive endpoint identifier. All pending scalars
are discarded, and any attempt to send more scalars will give an error.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error
*mcapi_status is set to the appropriate error defined below.
ERRORS
MCAPI_ENOT_HANDLE Argument is not a channel handle.
MCAPI_ENOT_OPEN The endpoint is not open.
MCAPI_EPARAM Incorrect request or mcapi_status parameter.
NOTE
Use the mcapi_test() , mcapi_wait() and mcapi_wait_any() functions to
query the status of and mcapi_cancel() function to cancel the operation.
SEE ALSO
************************************************************************/
void mcapi_sclchan_recv_close_i(
        MCAPI_IN mcapi_sclchan_recv_hndl_t receive_handle,
        MCAPI_OUT mcapi_request_t* request,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! valid_request_param(request)) {
      *mcapi_status = MCAPI_EPARAM;
    } else if (! mcapi_trans_valid_sclchan_recv_handle(receive_handle) ) {
      *mcapi_status = MCAPI_ENOT_HANDLE;
    } else if (! mcapi_trans_sclchan_recv_isopen (receive_handle)) {
      *mcapi_status = MCAPI_ENOT_OPEN;
    }
    mcapi_trans_sclchan_recv_close_i (receive_handle,request,mcapi_status);
  }
}
 
 
/***********************************************************************
NAME
mcapi_sclchan_send_close_i - closes channel on a send endpoint.
DESCRIPTION
Closes the send side of a channel. The corresponding calls are required on
both send and receive sides to ensure that the channel is properly closed.
It is a non-blocking function, and returns immediately.  send_handle is
the send endpoint identifier. Pending scalars at the receiver are not
discarded.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error
*mcapi_status is set to the appropriate error defined below.
ERRORS
MCAPI_ENOT_HANDLE Argument is not a channel handle.
MCAPI_ENOT_OPEN The endpoint is not open.
MCAPI_EPARAM Incorrect request or mcapi_status parameter.
NOTE
Use the mcapi_test() , mcapi_wait() and mcapi_wait_any() functions to
query the status of and mcapi_cancel() function to cancel the operation.
SEE ALSO
************************************************************************/
void mcapi_sclchan_send_close_i(
        MCAPI_IN mcapi_sclchan_send_hndl_t send_handle,
        MCAPI_OUT mcapi_request_t* request,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! valid_request_param(request)) {
      *mcapi_status = MCAPI_EPARAM;
    } else if (! mcapi_trans_valid_sclchan_recv_handle(send_handle) ) {
      *mcapi_status = MCAPI_ENOT_HANDLE;
    } else if (! mcapi_trans_sclchan_send_isopen (send_handle)) {
      *mcapi_status = MCAPI_ENOT_OPEN;
    }
    mcapi_trans_sclchan_send_close_i (send_handle,request,mcapi_status);
  }
}
 
 
/***********************************************************************
NAME
mcapi_test - tests if non-blocking operation has completed.
DESCRIPTION
Checks if a non-blocking operation has completed. The function returns
in a timely fashion. request is the identifier for the non-blocking
operation. The call only checks the completion of an operation and
doesn't affect any messages/packets/scalars.  If the specified request
completes and the pending operation was a send or receive operation,
the size parameter is set to the number of bytes that were either sent
or received by the non-blocking transaction.
RETURN VALUE
On success, MCAPI_TRUE is returned and *mcapi_status is set to
MCAPI_SUCCESS. If the operation has not completed MCAPI_FALSE is
returned and *mcapi_status is set to MCAPI_INCOMPLETE. On error
MCAPI_FALSE is returned and *mcapi_status is set to the appropriate
error defined below.
ERRORS
MCAPI_ENOTREQ_HANDLE Argument is not a valid request handle.
MCAPI_EPARAM Incorrect size and/or mcapi_status parameter.
NOTE
SEE ALSO
 mcapi_endpoint_t mcapi_get_endpoint_i(),
 mcapi_msg_send_i(),
 mcapi_msg_recv_i(),
 mcapi_connect_pktchan_i(),
 mcapi_open_pktchan_recv_i(),
 mcapi_open_pktchan_send_i(),
 mcapi_pktchan_send_i(),
 mcapi_pktchan_recv_i(),
 mcapi_pktchan_recv_close_i(),
 mcapi_pktchan_send_close_i(),
 mcapi_connect_sclchan_i(),
 mcapi_open_sclchan_recv_i(),
 mcapi_open_sclchan_send_i(),
 mcapi_sclchan_recv_close_i(),
 mcapi_sclchan_send_close_i()
************************************************************************/
mcapi_boolean_t mcapi_test(
        MCAPI_IN mcapi_request_t* request,
        MCAPI_OUT size_t* size,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  mcapi_boolean_t rc = MCAPI_FALSE;
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_INCOMPLETE;
    if (! valid_size_param(size)) {
      *mcapi_status = MCAPI_EPARAM;
       rc = MCAPI_TRUE;
    } else {
      rc = mcapi_trans_test_i(request,size,mcapi_status);
    }
  }
  return rc;
}
/***********************************************************************
NAME
mcapi_wait - waits for a non-blocking operation to complete.
DESCRIPTION
Wait until a non-blocking operation has completed. It is a blocking function
and returns when the operation has completed, has been canceled, or a timeout
has occurred. request is the identifier for the non-blocking operation. The
call only waits for the completion of an operation (all buffers referenced in
the operation have been filled or consumed and can now be safely accessed by
the application) and doesn't affect any messages/packets/scalars.  The size
parameter is set to number of bytes that were either sent or received by the
non-blocking transaction that completed (size is irrelevant for non-blocking
connect and close calls).  The mcapi_wait() call will return if the request
is cancelled by a call to mcapi_cancel(), and the returned mcapi_status will
indicate that the request was cancelled. The units for timeout are
implementation defined.  If a timeout occurs the returned status will indicate
that the timeout occurred.    A value of MCAPI_INFINITE for the timeout
parameter indicates no timeout is requested.
RETURN VALUE
On success, MCAPI_TRUE is returned and *mcapi_status is set to MCAPI_SUCCESS.
On error MCAPI_FALSE is returned and *mcapi_status is set to the appropriate
error defined below.
ERRORS
MCAPI_ENOTREQ_HANDLE Argument is not a valid request handle.
MCAPI_EREQ_CANCELED The request was canceled, by another thread (during the
waiting)
.
MCAPI_EREQ_TIMEOUT The operation timed out.
MCAPI_EPARAM Incorrect size and/or mcapi_status parameter.
NOTE
SEE ALSO
 mcapi_endpoint_t mcapi_get_endpoint_i(),
 mcapi_msg_send_i(),
 mcapi_msg_recv_i(),
 mcapi_connect_pktchan_i(),
 mcapi_open_pktchan_recv_i(),
 mcapi_open_pktchan_send_i(),
 mcapi_pktchan_send_i(),
 mcapi_pktchan_recv_i(),
 mcapi_pktchan_recv_close_i(),
 mcapi_pktchan_send_close_i(),
 mcapi_connect_sclchan_i(),
 mcapi_open_sclchan_recv_i(),
 mcapi_open_sclchan_send_i(),
 mcapi_sclchan_recv_close_i(),
 mcapi_sclchan_send_close_i()
************************************************************************/
mcapi_boolean_t mcapi_wait(
        MCAPI_IN mcapi_request_t* request,
        MCAPI_OUT size_t* size,
        MCAPI_OUT mcapi_status_t* mcapi_status,
        MCAPI_IN mcapi_timeout_t timeout)
{
  mcapi_boolean_t rc = MCAPI_FALSE;
 
   if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! valid_size_param(size)) {
      *mcapi_status = MCAPI_EPARAM;
      rc = MCAPI_TRUE;
    } else {
      rc = mcapi_trans_wait(request,size,mcapi_status,timeout);
    }
  }
  return rc;
}
 
/***********************************************************************
NAME
mcapi_wait_any - waits for any non-blocking operation in a list to complete.
DESCRIPTION
Wait until any non-blocking operation of a list has completed. It is a
blocking function and returns the index into the requests array (starting
from 0) indicating which of any outstanding operations has completed.
number is the number of requests in the array. requests is the array of
mcapi_request_t identifiers for the non-blocking operations. The call only
waits for the completion of an operation and doesn't affect any
messages/packets/scalars.  The size parameter is set to number of bytes
that were either sent or received by the non-blocking transaction that
completed (size is irrelevant for non-blocking connect and close calls).
The mcapi_wait_any() call will return 0 if all the requests are cancelled
by calls to mcapi_cancel() (during the waiting). The returned status will
indicate that a request was cancelled. The units for timeout are implementation
defined.  If a timeout occurs the mcapi_status parameter will indicate that
a timeout occurred.    A value of MCAPI_INFINITE for the timeout parameter
indicates no timeout is requested.
RETURN VALUE
On success, the index into the requests array of the mcapi_request_t
identifier that has completed or has been canceled is returned and
*mcapi_status is set to MCAPI_SUCCESS. On error MCAPI_NULL is returned
and *mcapi_status is set to the appropriate error defined below.
ERRORS
MCAPI_ENOTREQ_HANDLE Argument is not a valid request handle.
MCAPI_EREQ_CANCELED One of the requests was canceled, by another thread
(during the waiting).
MCAPI_EREQ_TIMEOUT The operation timed out.
MCAPI_EPARAM Incorrect requests, size, and/or mcapi_status parameter.
NOTE
SEE ALSO
 mcapi_endpoint_t mcapi_get_endpoint_i(),
 mcapi_msg_send_i(),
 mcapi_msg_recv_i(),
 mcapi_connect_pktchan_i(),
 mcapi_open_pktchan_recv_i(),
 mcapi_open_pktchan_send_i(),
 mcapi_pktchan_send_i(),
 mcapi_pktchan_recv_i(),
 mcapi_pktchan_recv_close_i(),
 mcapi_pktchan_send_close_i(),
 mcapi_connect_sclchan_i(),
 mcapi_open_sclchan_recv_i(),
 mcapi_open_sclchan_send_i(),
 mcapi_sclchan_recv_close_i(),
 mcapi_sclchan_send_close_i()
************************************************************************/
mcapi_int_t mcapi_wait_any(
        MCAPI_IN size_t number,
        MCAPI_IN mcapi_request_t** requests,
        MCAPI_OUT size_t* size,
        MCAPI_OUT mcapi_status_t* mcapi_status,
        MCAPI_IN mcapi_timeout_t timeout)
{
  mcapi_boolean_t rc = MCAPI_FALSE;
 
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    if (! valid_size_param(size)) {
      *mcapi_status = MCAPI_EPARAM;
      rc = MCAPI_TRUE;
    } else {
      rc = mcapi_trans_wait_any(number,requests,size,mcapi_status,timeout);
    }
  }
  return rc;
}
 
 
/***********************************************************************
NAME
mcapi_cancel - cancels an outstanding non-blocking operation.
DESCRIPTION
Cancels an outstanding non-blocking operation. It is a blocking function
and returns when the operation has been canceled. request is the identifier
for the non-blocking operation.  Any pending calls to mcapi_wait() or
mcapi_wait_any() for this request will also be cancelled. The returned
status of a canceled mcapi_wait() or mcapi_wait_any() call will indicate
that the request was cancelled.
RETURN VALUE
On success, *mcapi_status is set to MCAPI_SUCCESS. On error *mcapi_status
is set to the appropriate error defined below.
ERRORS
MCAPI_ENOTREQ_HANDLE Argument is not a valid request handle (the operation
may have completed).
MCAPI_EPARAM Incorrect mcapi_status parameter.
NOTE
SEE ALSO
 mcapi_endpoint_t mcapi_get_endpoint_i(),
 mcapi_msg_send_i(),
 mcapi_msg_recv_i(),
 mcapi_connect_pktchan_i(),
 mcapi_open_pktchan_recv_i(),
 mcapi_open_pktchan_send_i(),
 mcapi_pktchan_send_i(),
 mcapi_pktchan_recv_i(),
 mcapi_pktchan_recv_close_i(),
 mcapi_pktchan_send_close_i(),
 mcapi_connect_sclchan_i(),
 mcapi_open_sclchan_recv_i(),
 mcapi_open_sclchan_send_i(),
 mcapi_sclchan_recv_close_i(),
 mcapi_sclchan_send_close_i()
************************************************************************/
void mcapi_cancel(
        MCAPI_IN mcapi_request_t* request,
        MCAPI_OUT mcapi_status_t* mcapi_status)
{
  if (! valid_status_param(mcapi_status)) {
    if (mcapi_status != NULL) {
      *mcapi_status = MCAPI_EPARAM;
    }
  } else {
    *mcapi_status = MCAPI_SUCCESS;
    mcapi_trans_cancel(request,mcapi_status);
  }
}
 
 
 
Browse

Tools

Subversion Repositories funbase_ip_library

[/] [funbase_ip_library/] [trunk/] [TUT/] [ip.swp.api/] [mcapi_top/] [1.0/] [src/] [mcapi.c] - Blame information for rev 145

Line No.	Rev	Author	Line
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			`#include <mcapi.h>`
34			`#include <mcapi_trans.h>`
35			`#include <mcapi_config.h> /* for MCAPI version */`
36
37			`#include <string.h> /* for strncpy */`
38
39
40			`/* FIXME: (errata B5) anyone can get an endpoint handle and call receive on it. should`