ITC_drvdefs.h File Reference

Driver definitions for the ITC package. More...

#include <PBS/FORK.h>
#include <ITC/ITC_pubdefs.h>

Classes
struct	_ITC_Map
	Structure to hold node/task proxies for foreign nodes. More...
Defines
#define	ITC_PRT_K_SNID   (3)
#define	ITC_PRT_K_STID   (5)
#define	ITC_PRT_K_DNID   (3)
#define	ITC_PRT_K_DTID   (5)
#define	ITC_PRT_K_DQID   (3)
#define	ITC_PRT_K_PNID   (3)
#define	ITC_PRT_K_DID   (2)
#define	ITC_PRT_K_PID   (2)
#define	ITC_PRT_K_RSV   (4)
#define	ITC_PRT_K_VER   (2)
#define	ITC_PRT_V_SNID   ( 0 )
#define	ITC_PRT_V_STID   ( ITC_PRT_V_SNID + ITC_PRT_K_SNID )
#define	ITC_PRT_V_DNID   ( ITC_PRT_V_STID + ITC_PRT_K_STID )
#define	ITC_PRT_V_DTID   ( ITC_PRT_V_DNID + ITC_PRT_K_DNID )
#define	ITC_PRT_V_DQID   ( ITC_PRT_V_DTID + ITC_PRT_K_DTID )
#define	ITC_PRT_V_PNID   ( ITC_PRT_V_DQID + ITC_PRT_K_DQID )
#define	ITC_PRT_V_DID   ( ITC_PRT_V_PNID + ITC_PRT_K_PNID )
#define	ITC_PRT_V_PID   ( ITC_PRT_V_DID + ITC_PRT_K_DID )
#define	ITC_PRT_V_RSV   ( ITC_PRT_V_PID + ITC_PRT_K_PID )
#define	ITC_PRT_V_VER   ( ITC_PRT_V_RSV + ITC_PRT_K_RSV )
#define	ITC_PRT_M_SNID   (((1 << ITC_PRT_K_SNID ) - 1) << ITC_PRT_V_SNID )
#define	ITC_PRT_M_STID   (((1 << ITC_PRT_K_STID ) - 1) << ITC_PRT_V_STID )
#define	ITC_PRT_M_DNID   (((1 << ITC_PRT_K_DNID ) - 1) << ITC_PRT_V_DNID )
#define	ITC_PRT_M_DTID   (((1 << ITC_PRT_K_DTID ) - 1) << ITC_PRT_V_DTID )
#define	ITC_PRT_M_DQID   (((1 << ITC_PRT_K_DQID ) - 1) << ITC_PRT_V_DQID )
#define	ITC_PRT_M_PNID   (((1 << ITC_PRT_K_PNID ) - 1) << ITC_PRT_V_PNID )
#define	ITC_PRT_M_DID   (((1 << ITC_PRT_K_DID ) - 1) << ITC_PRT_V_DID )
#define	ITC_PRT_M_PID   (((1 << ITC_PRT_K_PID ) - 1) << ITC_PRT_V_PID )
#define	ITC_PRT_M_RSV   (((1 << ITC_PRT_K_RSV ) - 1) << ITC_PRT_V_RSV )
#define	ITC_PRT_M_VER   (((1 << ITC_PRT_K_VER ) - 1) << ITC_PRT_V_VER )
Typedefs
typedef unsigned int	ITC_cb_Dispatch (void *prm, const ITC_QueueItem *qitem, void *qipay, unsigned int qilen)
	Signature for an ITC dispatch plug-in routine.
typedef struct _ITC_Map	ITC_Map
	Typedef for struct _ITC_Map.
Functions
void *	ITC_allocFromQueue (ITC_Queue *queue, unsigned int siz, ITC_cb_Completion **rtn, void **cb0, void **cb1, void **cb2)
	Allocate memory from a queue.
unsigned int	ITC_convertDispatch (ITC_Task *task, ITC_QueueID qid, ITC_cb_Dispatch *rtn, void *prm)
	Modify the task dispatch routine with a new plug-in.
unsigned int	ITC_convertFork (ITC_Task *task, ITC_QueueID qid, FORK_cb_rtn rtn, void *prm)
	Modify a queue to be a pure fork queue.
void	ITC_copyCmdConfirm (ITC_Task *task, const char *cmd, WCT_time tim)
	Make a copy of a spacecraft command.
FORK_que *	ITC_getForkQueueHandle (ITC_TaskID tid, ITC_QueueID qid)
	Return the fork queue handle for the given task/queue.
unsigned int	ITC_getPacketProtocol (const ITC_QueueItem *qitem)
	Return the complete ITC protocol word.
unsigned int	ITC_insertMap (unsigned int nim, ITC_TaskID tid)
	Insert entries into the ITC node map.
ITC_Queue *	ITC_mapApid2Queue (unsigned short apid, ITC_TaskID *tid, ITC_QueueID *qid, unsigned int *scb)
	Return queue handle corresponding to APID.
ITC_Queue *	ITC_mapDst2Queue (unsigned int itc)
	Return queue handle corresponding to destination task/queue IDs.
unsigned int	ITC_redirectApid (unsigned int APID, ITC_TaskID ntid, ITC_QueueID nqid, ITC_TaskID *otid, ITC_QueueID *oqid)
	Redirect APID dispatch to a new task/queue.
unsigned int	ITC_removeMap (unsigned int nim)
	Remove entries from the ITC node map.
unsigned int	ITC_revertDispatch (ITC_Task *task, ITC_QueueID qid)
	Revert the task dispatch routine to the default plug-in.
void	ITC_sendCmdConfirm (ITC_Task *task, const char *cmd, unsigned int scb, WCT_time dtim, WCT_time xtim, unsigned int status)
	Send a telecommand execution status reponse.
ITC_NodeID	ITC_setPacketSrcNodeID (ITC_QueueItem *qitem, ITC_NodeID nid)
	Set the source node ID for the given queue item.
ITC_TaskID	ITC_setPacketSrcTaskID (ITC_QueueItem *qitem, ITC_TaskID tid)
	Set the source task ID for the given queue item.

---

Detailed Description

Driver definitions for the ITC package.

CVS $Id: ITC_drvdefs.h,v 1.7 2011/03/25 21:01:10 apw Exp $

Author:

A.P.Waite

ITC_drvdefs.h defines a number of auxiliary entry points for use by driver level code.

Warning:

The entry points defined here are intended for use by hardware drivers (or their surrogates) only. Standard application code should have no reason to call these entry points.

---

Function Documentation

void* ITC_allocFromQueue	(	ITC_Queue *	queue,
		unsigned int	siz,
		ITC_cb_Completion **	rtn,
		void **	cb0,
		void **	cb1,
		void **	cb2
	)

Allocate memory from a queue.

Parameters:

	queue	(in) Queue handle
	siz	(in) Bytes to allocate
	rtn	(out) Memory deallocation callback routine
	cb0	(out) Memory deallocation callback routine parameter 0
	cb1	(out) Memory deallocation callback routine parameter 1
	cb2	(out) Memory deallocation callback routine parameter 2

Return values:

	NULL	Memory not allocated
	x	Pointer to allocated memory

References _ITC_Queue::chk, ITC_icb, _ITC_Queue::memPrm, _ITC_Queue::memRtn, _ITC_Queue::qid, _ITC_Control::rwi, and _ITC_Queue::tid.

unsigned int ITC_convertDispatch	(	ITC_Task *	task,
		ITC_QueueID	qid,
		ITC_cb_Dispatch *	rtn,
		void *	prm
	)

Modify the task dispatch routine with a new plug-in.

Parameters:

	task	(in) Task handle
	qid	(in) Queue ID
	rtn	(in) Plug-in routine
	prm	(in) Plug-in routine parameter

Warning:

Caller is responsible for ensuring the persistence and validity of the context parameter. This routine only captures pointers.

Return values:

	ITC_CTLSTAT	ITC control block not in state initialized
	ITC_NOTINIT	ITC control block does not exist
	ITC_QUEUSTAT	Queue not in state initialized
	ITC_SUCCESS	Success
	ITC_TASKDISP	NULL dispatch routine specified
	ITC_TASKHNDL	Task handle is invalid
	ITC_TASKSTAT	Invalid task state for this operation
	ITC_TASKTYP	Invalid call for a lightweight task
	ITC_VARRNG	Out of range variable detected

References checkState(), _ITC_Queue::dspPrm, _ITC_Queue::dspRtn, ITC_CTL_INITIALIZED, ITC_icb, ITC_K_USERQS, ITC_L_USERQS, ITC_qpl, ITC_TSK_INITIALIZED, ITC_TSK_TYP_LITE, _ITC_Control::mtx, _ITC_Task::tid, and _ITC_Task::typ.

unsigned int ITC_convertFork	(	ITC_Task *	task,
		ITC_QueueID	qid,
		FORK_cb_rtn	rtn,
		void *	prm
	)

Modify a queue to be a pure fork queue.

Parameters:

	task	(in) Task handle
	qid	(in) Queue ID
	rtn	(in) Fork callback routine
	prm	(in) Fork callback routine parameter

Warning:

Caller is responsible for ensuring the persistence and validity of the context parameter. This routine only captures pointers.

Return values:

	ITC_CTLSTAT	ITC control block not in state initialized
	ITC_NOTINIT	ITC control block does not exist
	ITC_QUEUSTAT	Queue not in state initialized
	ITC_SUCCESS	Success
	ITC_TASKDISP	NULL dispatch routine specified
	ITC_TASKHNDL	Task handle is invalid
	ITC_TASKSTAT	Invalid task state for this operation
	ITC_TASKTYP	Invalid call for a lightweight task
	ITC_VARRNG	Out of range variable detected

References checkState(), _ITC_Queue::frk, _ITC_Queue::frkPrm, _ITC_Queue::frkRtn, ITC_CTL_INITIALIZED, ITC_icb, ITC_K_USERQS, ITC_L_USERQS, ITC_qpl, ITC_TSK_INITIALIZED, ITC_TSK_TYP_LITE, _ITC_Control::mtx, _ITC_Task::tid, and _ITC_Task::typ.

void ITC_copyCmdConfirm	(	ITC_Task *	task,
		const char *	cmd,
		WCT_time	tim
	)

Make a copy of a spacecraft command.

Parameters:

	task	(in) Task handle
	cmd	(in) Pointer to CCSDS telecommand
	tim	(in) Time command was dequeued

ITC_copyCmdConfirm() makes a copy of a spacecraft command before any damage can be done to it by the command callback routine.

References _ITC_TaskConfirm::cmd, _ITC_Task::cnf, _ITC_CommandCount::cnt, _ITC_Task::sav, and _ITC_CommandCount::tim.

Referenced by ITC_dispatch().

FORK_que* ITC_getForkQueueHandle	(	ITC_TaskID	tid,
		ITC_QueueID	qid
	)

Return the fork queue handle for the given task/queue.

Parameters:

	tid	(in) Task ID
	qid	(in) Queue ID

Return values:

	NULL	Error (no such task, no such queue, task not started)
	x	The fork queue handle

ITC_getForkQueueHandle() returns the fork queue handle for task tid, queue qid.

Warning:

Fork queue handles are only known for ITC tasks in state "started".

References _ITC_Task::chk, ITC_L_QUEUES, ITC_L_TASKS, ITC_qpl, ITC_tpl, ITC_TSK_STARTED, ITC_TSK_STARTING, and _ITC_Task::state.

unsigned int ITC_getPacketProtocol

(

const ITC_QueueItem *

qitem

)

Return the complete ITC protocol word.

Parameters:

qitem

(in) Queue item

Returns:

The complete ITC protocol word

References _ITC_QueueItem::itcp.

unsigned int ITC_insertMap	(	unsigned int	nim,
		ITC_TaskID	tid
	)

Insert entries into the ITC node map.

Parameters:

	nim	(in) Mask of nodes to be mapped to the given task ID
	tid	(in) Task ID that will serve as proxy for the listed nodes

Return values:

	ITC_CTLSTAT	ITC control block not in state initialized
	ITC_NOTINIT	ITC system not initialized
	ITC_SUCCESS	Success

ITC_insertMap() puts proxy node/task entries into the ITC node map.

References ITC_CTL_INITIALIZED, _ITC_Control::map, _ITC_Control::mtx, _ITC_Control::nim, _ITC_Map::ptid, _ITC_Control::rwi, and _ITC_Control::state.

ITC_Queue* ITC_mapApid2Queue	(	unsigned short	APID,
		ITC_TaskID *	tid,
		ITC_QueueID *	qid,
		unsigned int *	scb
	)

Return queue handle corresponding to APID.

Parameters:

	APID	(in) Application ID
	tid	(out) Task ID
	qid	(out) Queue ID
	scb	(out) Is broadcast command (0/1 => not broadcast/broadcast)

Return values:

	NULL	No mapping possible
	x	Queue handle

References ITC_apl, ITC_QID_NONE, ITC_qpl, ITC_TID_NONE, _ITC_Apid::qid, _ITC_Apid::tid, and validApidRx().

ITC_Queue* ITC_mapDst2Queue

(

unsigned int

itcp

)

Return queue handle corresponding to destination task/queue IDs.

Parameters:

itcp

(in) ITC protocol word

Return values:

	NULL	No mapping possible
	x	Queue handle

References ITC_icb, ITC_qpl, ITC_TID_NONE, _ITC_Control::map, _ITC_Control::nid, and _ITC_Map::ptid.

unsigned int ITC_redirectApid	(	unsigned int	APID,
		ITC_TaskID	ntid,
		ITC_QueueID	nqid,
		ITC_TaskID *	otid,
		ITC_QueueID *	oqid
	)

Redirect APID dispatch to a new task/queue.

Parameters:

	APID	(in) APID to redirect
	ntid	(in) New task destination of APID dispatch
	nqid	(in) New queue destination of APID dispatch
	otid	(out) Old task destination of APID dispatch
	oqid	(out) Old queue destination of APID dispatch

Return values:

	ITC_CTLSTAT	ITC control block not in state initialized
	ITC_NOTINIT	ITC control block does not exist
	ITC_RAWDBL	Raw protocol handler for this queue already defined
	ITC_RAWRTN	Cannot specify a NULL routine
	ITC_QUEUSTAT	Queue not in state initialized
	ITC_SUCCESS	Success
	ITC_TASKHNDL	Task handle is invalid
	ITC_TASKSTAT	Invalid task state for this operation
	ITC_VARRNG	Out of range variable detected

References checkState(), _ITC_Task::chk, ITC_apl, ITC_CTL_INITIALIZED, ITC_icb, ITC_K_APPS, ITC_K_USERQS, ITC_L_APPS, ITC_L_USERQS, ITC_tpl, ITC_TSK_INITIALIZED, ITC_TSK_TYP_APP, _ITC_Control::mtx, _ITC_Apid::qid, _ITC_Task::state, _ITC_Apid::tid, _ITC_Task::typ, and validApidRx().

unsigned int ITC_removeMap

(

unsigned int

nim

)

Remove entries from the ITC node map.

Parameters:

nim

(in) Mask of nodes to be mapped

Return values:

	ITC_CTLSTAT	ITC control block not in state initialized
	ITC_NOTINIT	ITC system not initialized
	ITC_SUCCESS	Success

ITC_removeMap() removes proxy node/task entries from the ITC node map.

References ITC_CTL_INITIALIZED, ITC_TID_NONE, _ITC_Control::map, _ITC_Control::mtx, _ITC_Control::nim, _ITC_Map::ptid, _ITC_Control::rwi, and _ITC_Control::state.

unsigned int ITC_revertDispatch	(	ITC_Task *	task,
		ITC_QueueID	qid
	)

Revert the task dispatch routine to the default plug-in.

Parameters:

	task	(in) Task handle
	qid	(in) Queue ID

Return values:

	ITC_APIDRNG	Invalid APID
	ITC_APIDTBL	No APID table entry for APID
	ITC_CTLSTAT	ITC control block not in state initialized
	ITC_NOTINIT	ITC control block does not exist
	ITC_SUCCESS	Success
	ITC_TASKHNDL	Task handle is invalid
	ITC_TASKSTAT	Invalid task state for this operation
	ITC_TASKTYP	Invalid call for a lightweight task
	ITC_VARRNG	Out of range variable detected

References checkState(), _ITC_Queue::dspPrm, _ITC_Queue::dspRtn, ITC_CTL_INITIALIZED, ITC_dispatchApp(), ITC_icb, ITC_K_USERQS, ITC_L_USERQS, ITC_qpl, ITC_TSK_INITIALIZED, ITC_TSK_TYP_LITE, _ITC_Control::mtx, _ITC_Task::tid, and _ITC_Task::typ.

void ITC_sendCmdConfirm	(	ITC_Task *	task,
		const char *	cmd,
		unsigned int	scb,
		WCT_time	dtim,
		WCT_time	xtim,
		unsigned int	status
	)

Send a telecommand execution status reponse.

Parameters:

	task	(in) Task handle
	cmd	(in) Pointer to CCSDS telecommand
	scb	(in) Spacecraft broadcast APID flag
	dtim	(in) Time command dequeued
	xtim	(in) Time execution completed
	status	(in) Command completion code

References _ITC_CommandCount::bad, _ITC_Flags::bf, _ITC_TaskConfirm::cmd, _ITC_CmdConfirm_Tlm::cmd_hdr, _ITC_Task::cnf, _ITC_CmdConfirm_Tlm::deq_lsui, _ITC_CmdConfirm_Tlm::deq_msui, _ITC_CmdConfirm_Tlm::drp, _ITC_TaskConfirm::drp, _ITC_CmdConfirm_Tlm::exe_lsui, _ITC_CmdConfirm_Tlm::exe_msui, _ITC_CmdConfirm_Tlm::flags, ITC_bind(), ITC_CMDCONFIRM_TLM_APID, ITC_DID_APID, ITC_icb, ITC_LVL_ALL, ITC_NID_SC, ITC_PID_ACK, ITC_QID_CTL, ITC_rollback(), ITC_send(), ITC_TID_ANON, _ITC_TaskConfirm::level, _ITC_Control::nid, _ITC_CmdConfirm_Tlm::nid, _ITC_TaskConfirm::prm, _ITC_TaskConfirm::rtn, _ITC_Task::sav, _ITC_CmdConfirm_Tlm::status, _ITC_CmdConfirm_Tlm::tid, _ITC_Task::tid, and _ITC_Flags::us.

Referenced by ITC_dispatch().

ITC_NodeID ITC_setPacketSrcNodeID	(	ITC_QueueItem *	qitem,
		ITC_NodeID	nid
	)

Set the source node ID for the given queue item.

Parameters:

	qitem	(in) Queue item pointer
	nid	(in) ITC node ID

Return values:

x

Previous value of node ID (ITC_NID_NONE on error)

Warning:

This entry point is provided for use by ITC driver callbacks (lightweight tasks). There should never be any reason for other tasks to call this entry point.

References ITC_L_NODES, ITC_NID_NONE, and _ITC_QueueItem::itcp.

ITC_TaskID ITC_setPacketSrcTaskID	(	ITC_QueueItem *	qitem,
		ITC_TaskID	tid
	)

Set the source task ID for the given queue item.

Parameters:

	qitem	(in) Queue item pointer
	tid	(in) ITC task ID

Return values:

x

Previous value of task ID (ITC_TID_NONE on error)

Warning:

This entry point is provided for use by ITC driver callbacks (lightweight tasks). There should never be any reason for other tasks to call this entry point.

References ITC_L_TASKS, ITC_TID_NONE, and _ITC_QueueItem::itcp.