GRBU_merge.c File Reference

Handles merging of packets of photons for the GRB algorithm. More...

#include <string.h>
#include <GRB/GRB_pktdef.h>
#include <GRB/GRB_msgdef.h>
#include <GRB/GRB_siu.h>
#include <GRBU/GRBU_msgs.h>
#include <GRBU/GRBU_pubdefs.h>
#include <ITC/ITC_pubdefs.h>
#include <MDB/MDB_pubdefs.h>
#include <PBS/FFS.ih>
#include <PBS/L.ih>
#include <GRBU_prvdefs.h>

Functions
static void	drain (GRBU_MergeControl *mcb, GRBU_Source *src, unsigned int msk)
	Merge photons from available packets.
static void	merge (GRBU_MergeControl *mcb)
	Merge photons from available packets.
static void	update (GRBU_MergeControl *mcb, unsigned int cpu)
	Update control structures for new CPU packet.
unsigned int	GRBU_mergePacket (GRBU_pktMerge *mrg, const GRB_pktHdr *hdr, GRBU_mrgDisposeRtn rtn, void *prm)
	Add a new merge packet to the merge process.
void	GRBU_mergeReset ()
	Reset the merge machine.
unsigned int	GRBU_mergeSizeof ()
	Size of a merge packet structure.
unsigned int	GRBU_mergeStart (unsigned int msk, GRB_siuStartRtn start_rtn, void *start_prm, GRB_siuProcessRtn exec_rtn, void *exec_prm, GRB_siuStopRtn stop_rtn, void *stop_prm)
	Start the merging process.
Variables
GRBU_MergeControl	GRBU_mergeControl
	Control block for the GRB photon merging processor.

---

Detailed Description

Handles merging of packets of photons for the GRB algorithm.

CVS $Id: GRBU_merge.c,v 1.9 2011/03/26 23:16:12 russell Exp $

Author:

A.P.Waite

---

Function Documentation

static void drain	(	GRBU_MergeControl *	mcb,
		GRBU_Source *	src,
		unsigned int	msk
	)			[static]

Merge photons from available packets.

Parameters:

	mcb	(in) Merge control block
	src	(in) Source control block
	msk	(in) Source (CPU) declaring "end" (in mask form).

drain() will mark the given source (CPU) out of the "needed" mask, and drain down all the packets associated with the given source. Called when a packet's processing is complete and the packet is marked with the close reason GRB_PKT_CLOSE_REASON_STOP.

References _GRBU_pktMerge::dispose_prm, _GRBU_pktMerge::dispose_rtn, _GRBU_MergeControl::have, _GRBU_Source::mrg, _GRBU_MergeControl::need, and _GRBU_Source::queue.

Referenced by update().

unsigned int GRBU_mergePacket	(	GRBU_pktMerge *	mrg,
		const GRB_pktHdr *	hdr,
		GRBU_mrgDisposeRtn	rtn,
		void *	prm
	)

Add a new merge packet to the merge process.

Parameters:

	mrg	(in) A merge packet header
	hdr	(in) Pointer to the header of the real data packet
	rtn	(in) Callback routine to dispose of the merge packet
	prm	(in) User parameter to the disposal routine

Return values:

	GRBU_ENDMERGE	End of merge run
	GRBU_NULLPARM	NULL parameter in calling sequence
	GRBU_SRCOFF	No merge packets expected from this source
	GRBU_SRCEND	Source has sent stop packet, then another packet
	GRBU_SUCCESS	Success

Receive a new GRB packet and push it through merging.

References _GRBU_pktMerge::dispose_prm, _GRBU_pktMerge::dispose_rtn, _GRBU_MergeControl::have, _GRBU_pktMerge::hdr, merge(), _GRBU_MergeControl::need, _GRBU_Source::queue, _GRBU_MergeControl::src, update(), and _GRBU_MergeControl::want.

unsigned int GRBU_mergeStart	(	unsigned int	msk,
		GRB_siuStartRtn	start_rtn,
		void *	start_prm,
		GRB_siuProcessRtn	exec_rtn,
		void *	exec_prm,
		GRB_siuStopRtn	stop_rtn,
		void *	stop_prm
	)

Start the merging process.

Parameters:

	msk	[in] Mask of sources (CPUs) to merge
	start_rtn	[in] Callback to inform photon processor of "start"
	start_prm	[in] User parameter to "start_rtn()"
	exec_rtn	[in] Callback for each photon
	exec_prm	[in] User parameter to "start_rtn()"
	stop_rtn	[in] Callback to inform photon processor of "stop"
	stop_prm	[in] User parameter to "start_rtn()"

Return values:

	GRBU_SRCMSK	Invalid source (CPU) mask
	GRBU_STARTPRM	No photon processing routine provided
	GRBU_SUCCESS	Success

GRBU_mergeStart() starts a new merge process. It clears out any previous context and resets for the new CPU mask set and callback definitions. The CPU mask set uses the ITC CPU definitions and the provided mask must make sense (i.e. define at least one valid CPU and must not define any invalid CPUs). A photon processing routine must be defined with the exec_rtn parameter. The "start" and "stop" callbacks are optional and will not be called if defined as NULL.

References _GRBU_MergeControl::exec_prm, _GRBU_MergeControl::exec_rtn, GRBU_mergeReset(), _GRBU_MergeControl::have, _GRBU_MergeControl::need, _GRBU_MergeControl::stop_prm, _GRBU_MergeControl::stop_rtn, and _GRBU_MergeControl::want.

static void merge

(

GRBU_MergeControl *

mcb

)

[static]

Merge photons from available packets.

Parameters:

mcb

(in) Merge control block

Several sources (usually EPUs) are responsible for picking out possible GRB candidate photons. Each source batches such candidates into packets for transmission to the SIU, where the actual GRB spotting algorithm is run. Photons within a batch from a single source are always time ordered. The difficulty is that with many possible sources, the photons have no particular time order between packets from different sources. That's where merge() comes in. It's sole responsibility is to receive these packets and to merge the photons into a single time ordered stream.

References _GRBU_Source::cnt, _GRBU_MergeControl::exec_prm, _GRBU_MergeControl::exec_rtn, _GRBU_MergeControl::have, _GRBU_Source::idx, _GRBU_Source::key, _GRBU_Source::msg, _GRBU_MergeControl::need, _GRBU_MergeControl::src, _GRBU_MergeControl::stop_prm, _GRBU_MergeControl::stop_rtn, and update().

Referenced by GRBU_mergePacket().

static void update	(	GRBU_MergeControl *	mcb,
		unsigned int	cpu
	)			[static]

Update control structures for new CPU packet.

Parameters:

	mcb	(in) Merge process control block
	cpu	(in) Index of contributing source (CPU)

References _GRBU_Source::cnt, _GRBU_pktMerge::dispose_prm, _GRBU_pktMerge::dispose_rtn, drain(), _GRBU_MergeControl::have, _GRBU_pktMerge::hdr, _GRBU_Source::idx, _GRBU_Source::key, _GRBU_Source::mrg, _GRBU_Source::msg, _GRBU_Source::queue, _GRBU_Source::seq, and _GRBU_MergeControl::src.

Referenced by GRBU_mergePacket(), and merge().