Specifications

32 Cross Bus Interface HighWire MTP-2 - 1.2, September 4, 2002
component for the message (CBI_M2_MSG_FOR_XMISSION), then a data
buffer must also be supplied. The data buffer is subject to the same
constraints as the control buffer, except that the additional space must be
provided both at the start and the tail of the data, and the amounts of empty
space provided are determined by the send_data_hdr_size and
send_data_tail_size fields of the CBI_M2_OPEN response.
The MTP3 then invokes the cbi_send() API to dispatch the message. The
cbi_send() API may either complete synchronously and return
CBI_RC_SYNC_COMPLETE or asynchronously complete and return
CBI_RC_ASYNC_COMPLETE. If asynchronous completion is indicated, the
application is responsible for re-transmitting the message when resources
become available.
4-2-6. Receiving messages from
MTP2
Once cbi_open() has been successfully called, an application is notified of
arriving messages via the CBI_MSG_AVAIL_CALLBACK. The CBI library invokes
this callback on a separate thread of execution. The application must then
immediately issue the cbi_recv() call to receive the message (the
application may issue this call on the same thread as it receives the callback
if it so desires, or it may issue it on an alternative thread). The cbi_recv()
call may complete with the CBI_RC_SYNC_COMPLETE return code, in which
case the message has been fully received into the application’s buffer.
Alternatively, the cbi_recv() call may complete with the
CBI_RC_ASYNC_COMPLETE return code, in which case the message was not
completely available. In this later case, the buffers do not contain a complete
message. The same buffers must be passed back into cbi_recv() the next
time the CBI library signals the application again with the
CBI_MSG_AVAIL_CALLBACK when more of the message becomes available. In
this case, the application must not alter, re-use, or free such buffers. The CBI
library may also return CBI_RC_NO_MSG, in which case the message was
destined for the library itself (in this case, however, the buffers are returned to
the application which may reuse or free them as it sees fit). Note that the
application is responsible for providing any header and/or tail bytes that it
requires.
4-2-7. Send-side flow control
(HWMTP2 for Solaris only)
When the application invokes cbi_send(), the library will normally be able
to complete the send operation synchronously and return the
CBI_RC_SYNC_COMPLETE return code. In this case, the application may free
or re-use the buffers which contained the message.
If, on the other hand, the library is unable to send a complete message
(instead sending only part or none of the message) it returns
CBI_RC_ASYNC_COMPLETE. In this case the application must re-transmit the
flow controlled message once resources become available for cross bus
transfer.