ITC_send.c File Reference

Packet sending routines for ITC. More...

#include <MSG/MSG_pubdefs.h>
#include <ITC/ITC_drvdefs.h>
#include <ITC/ITC_msgs.h>
#include <ITC_prvdefs.h>

Functions
static unsigned int	validSend (ITC_NodeID dnid, ITC_TaskID dtid, ITC_QueueID dqid, ITC_DispID did, ITC_ProtID pid)
	Check the send arguments for validity.
unsigned int	ITC_bind (ITC_QueueItem *qitem, void *qipay, unsigned int qilen, ITC_NodeID dnid, ITC_TaskID dtid, ITC_QueueID dqid, ITC_DispID did, ITC_ProtID pid, ITC_cb_Completion *rtn, void *prm0, void *prm1, void *prm2)
	Bind a queue item descriptor.
void	ITC_complete (const ITC_QueueItem *qitem, unsigned int status)
	Call back the user provided completion routine (often a free).
unsigned int	ITC_forward (const ITC_QueueItem *qitem, ITC_NodeID dnid, ITC_TaskID dtid, ITC_QueueID dqid, ITC_DispID did, ITC_ProtID pid)
	Forward a queue item to another destination.
void	ITC_rollback (const ITC_QueueItem *qitem, unsigned int status)
	Call back the user provided completion routine (often a free).
unsigned int	ITC_send (ITC_QueueItem *qitem)
	Send a queue item to a destination queue.
unsigned int	ITC_sizeofQueueItem ()
	return the size of a queue item header (bytes)

---

Detailed Description

Packet sending routines for ITC.

CVS $Id: ITC_send.c,v 1.16 2011/03/25 21:01:11 apw Exp $

Author:

A.P.Waite

---

Function Documentation

unsigned int ITC_bind	(	ITC_QueueItem *	qitem,
		void *	qipay,
		unsigned int	qilen,
		ITC_NodeID	dnid,
		ITC_TaskID	dtid,
		ITC_QueueID	dqid,
		ITC_DispID	did,
		ITC_ProtID	pid,
		ITC_cb_Completion *	rtn,
		void *	prm0,
		void *	prm1,
		void *	prm2
	)

Bind a queue item descriptor.

Parameters:

	qitem	(in) Queue item descriptor
	qipay	(in) Location of buffer to be queued
	qilen	(in) Length of buffer to be queued (bytes)
	dnid	(in) Destination node ID
	dtid	(in) Destination task ID
	dqid	(in) Destination queue ID
	did	(in) Dispatch protocol ID
	pid	(in) Hardware protocol ID
	rtn	(in) Completion routine
	prm0	(in) Completion routine user parameter 0
	prm1	(in) Completion routine user parameter 1
	prm2	(in) Completion routine user parameter 2

Return values:

	ITC_SUCCESS	Success
	ITC_VARNULL	NULL variable (pointer) detected
	ITC_VARRNG	Out of range variable detected

ITC_bind() binds a queue item descriptor (connects together all the elements of a message: the location of the message, the destination of the message and the disposal method of the message).

References _ITC_QueueItem::compPrm0, _ITC_QueueItem::compPrm1, _ITC_QueueItem::compPrm2, _ITC_QueueItem::compRtn, ITC_getTaskID(), ITC_icb, ITC_TID_ANON, ITC_TID_NONE, _ITC_QueueItem::itcp, _ITC_QueueItem::len, _ITC_Control::nid, _ITC_QueueItem::pay, and validSend().

Referenced by ITC_sendCmdConfirm().

void ITC_complete	(	const ITC_QueueItem *	qitem,
		unsigned int	status
	)

Call back the user provided completion routine (often a free).

Parameters:

	qitem	(in) Queue item
	status	(in) Completion status

Warning:

If this routine is being called on the send side of a task to task communication in order to back out of a failed send, please use the routine ITC_rollback() instead. The completion routine will be provided with the proper flag to indicate a send side completion request.

This routine is called at the end of ITC dispatch and execution to allow the sender of an ITC packet to perform any completion processing. The most common use of a completion routine is to free memory.

References _ITC_QueueItem::compPrm0, _ITC_QueueItem::compPrm1, _ITC_QueueItem::compPrm2, and _ITC_QueueItem::compRtn.

Referenced by ITC_dispatch().

unsigned int ITC_forward	(	const ITC_QueueItem *	qitem,
		ITC_NodeID	dnid,
		ITC_TaskID	dtid,
		ITC_QueueID	dqid,
		ITC_DispID	did,
		ITC_ProtID	pid
	)

Forward a queue item to another destination.

Parameters:

	qitem	(in) Queue item descriptor
	dnid	(in) Destination node ID
	dtid	(in) Destination task ID
	dqid	(in) Destination queue ID
	did	(in) Dispatch protocol ID
	pid	(in) Hardware protocol ID

Return values:

	ITC_SENDNID	Destination node not reachable
	ITC_SENDPRX	Proxy task for destination node not started
	ITC_SENDQID	Destination queue not available
	ITC_SENDTID	Destination task not started
	ITC_SUCCESS	Success
	ITC_VARNULL	NULL variable (pointer) detected
	ITC_VARRNG	Out of range variable detected

ITC_forward() sends an existing, fully described queue item to another destination. If successful, it returns the code ITC_FORWARD (level "success"). If this queue item is being forwarded from within the standard task level dispatch, this code should be returned from the dispatch callback so that the dispatcher doesn't free the queue item.

References ITC_send(), _ITC_QueueItem::itcp, and validSend().

void ITC_rollback	(	const ITC_QueueItem *	qitem,
		unsigned int	status
	)

Call back the user provided completion routine (often a free).

Parameters:

	qitem	(in) Queue item
	status	(in) Completion status

Warning:

The primary use of this entry point is to back out of a failed send. This is sometimes necessary when a ring buffer is used to send ITC packets between tasks. The send side needs to perform "head" frees, whereas the receive side needs to perform "tail" frees. Calling this entry point on the send side will ensure that the user's callback routine will receive the correct flag to indicate a "send side" completion.

References _ITC_QueueItem::compPrm0, _ITC_QueueItem::compPrm1, _ITC_QueueItem::compPrm2, and _ITC_QueueItem::compRtn.

Referenced by ITC_sendCmdConfirm().

unsigned int ITC_send

(

ITC_QueueItem *

qitem

)

Send a queue item to a destination queue.

Parameters:

qitem

(in) Queue item descriptor

Return values:

	ITC_SENDNID	Destination node not reachable
	ITC_SENDPRX	Proxy task for destination node not started
	ITC_SENDQID	Destination queue not available
	ITC_SENDTID	Destination task not started
	ITC_SUCCESS	Success
	ITC_VARNULL	NULL variable (pointer) detected

ITC_sendQueueItem() sends a packet to a destination. The queue item must be fully composed and is assumed to have integrity. This routine should never be made part of the public interface.

References _ITC_Queue::cnt, _ITC_Queue::fqi, ITC_icb, ITC_qpl, ITC_TID_NONE, ITC_tpl, ITC_TSK_STARTED, _ITC_QueueItem::itcp, _ITC_Control::map, _ITC_Control::nid, _ITC_Map::pnid, _ITC_Map::ptid, _ITC_Control::rwi, and _ITC_Task::state.

Referenced by ITC_forward(), and ITC_sendCmdConfirm().

unsigned int ITC_sizeofQueueItem

(

void

)

return the size of a queue item header (bytes)

ITC_sizeofQueueItem()returns the size of a queue item header (in bytes).

static unsigned int validSend	(	ITC_NodeID	dnid,
		ITC_TaskID	dtid,
		ITC_QueueID	dqid,
		ITC_DispID	did,
		ITC_ProtID	pid
	)			[inline, static]

Check the send arguments for validity.

Parameters:

	dnid	(in) Destination node ID
	dtid	(in) Destination task ID
	dqid	(in) Destination queue ID
	did	(in) Dispatch protocol ID
	pid	(in) Hardware protocol ID

Return values:

	ITC_SUCCESS	Success
	ITC_VARRNG	Variable out of range

References ITC_K_DISPS, ITC_K_PROTS, ITC_K_USERQS, ITC_L_DISPS, ITC_L_NODES, ITC_L_PROTS, ITC_L_TASKS, and ITC_L_USERQS.

Referenced by ITC_bind(), and ITC_forward().