LSEC_p.h File Reference

Definitions for the internal LSEC routines. More...

#include <LSEC/LSEC.h>
#include <LSEC/LSEC_ctx.h>
#include <EDS/EBF_dir.h>
#include <EDS/EBF_ctb.h>
#include <stdio.h>

Typedefs
typedef struct _LSEC_compaction	LSEC_compaction
	Declaration of the opaque compaction structure.
typedef struct _LSEC_calEvent	LSEC_calEvent
	Declaration of the opaque CAL event structure.
typedef struct _LSEC_compression	LSEC_compression
	Declaration of the opaque compression structure.
typedef struct _LSEC_consignment	LSEC_consignment
	Declaration of the opaque consignment structure.
typedef struct _LSEC_event	LSEC_event
	Declaration of the opaque event structure.
typedef unsigned	LSEC_eventProcRtn (void *parm, EBF_dir *dir)
	Event processing routine.
Functions
LSEC_consignment *	LSEC_consCreate (unsigned cpuid, unsigned srcid, unsigned cap, LSEC_compaction *cpc, LSEC_event *evt, long long *times)
	Create a new consignment.
LSEC_ctx *	LSEC_consCtxGet (LSEC_consignment *cns)
	Get the address of the context structure.
void	LSEC_consDelete (LSEC_consignment *cns)
	Free the previously allocated consignment structure.
unsigned	LSEC_consEventCal (void *parm, EBF_dir *dir)
	Process a compressed CAL event.
unsigned	LSEC_consEventImm (void *parm, EBF_dir *dir)
	Process an event immediately.
void	LSEC_consPrepare (LSEC_consignment *cns, unsigned runid, unsigned mode, LSEC_compLevel comp)
	Prepare for a new calibration run.
unsigned	LSEC_consProcess (LSEC_consignment *cns)
	Process a consignment.
void	LSEC_consReason (LSEC_consignment *cns, int reason)
	Set the current datagram close reason.
void	LSEC_accumCalMeans (LSEC_compaction *cpc, unsigned int *evt, EBF_dir *dir)
	Accumulate the means of the CAL log end values.
unsigned	LSEC_checkCalCompaction (LSEC_compaction *cpc)
	Check the CAL substructure for errors.
void	LSEC_clearCalCompaction (LSEC_compaction *cpc)
	Clear away any CAL context from a previous cycle.
unsigned int *	LSEC_copyUser (LSEC_compaction *cpc, unsigned int *buf)
	Copy datagram header information into the buffer.
void	LSEC_deleteCompaction (LSEC_compaction *cpc)
	Free memory previously allocated with a call to LSEC_newCompaction.
unsigned int	LSEC_eventSizeCal (const LSEC_calEvent *event)
	Get the size of a saved CAL event.
EBF_ctb *	LSEC_gemContribCal (const LSEC_calEvent *event)
	Get the GEM contribution address from a saved CAL event.
void	LSEC_histoCalMeans (LSEC_compaction *cpc)
	Calculate and histogram the mean values for the CAL log ends.
void	LSEC_histogramCal (LSEC_compaction *cpc, LSEC_calEvent *event)
	Perform histogramming of the CAL data.
LSEC_compaction *	LSEC_newCompaction (unsigned cap, long long *times)
	Allocate memory for an LSEC_compaction structure and all the substructures.
unsigned	LSEC_processCal (LSEC_compaction *cpc)
	Process the CAL compression structures.
void	LSEC_reportCalCompaction (LSEC_compaction *exp, FILE *fp)
	Write CAL compression table contents to an ASCII file.
void	LSEC_setContext (LSEC_compaction *cpc, const LSEC_ctx *ctx)
	Set the context information pointer.
void	LSEC_setMode (LSEC_compaction *cpc, unsigned mode)
	Set the calibration mode.
unsigned int	LSEC_sizeofUser (LSEC_compaction *cpc)
	Calculate the number of 32-bit words required to hold the tables against which the contributions will be encoded.
unsigned	LSEC_checkCompression (LSEC_compression *cpr)
	Check if there were errors during the histogram or encode operations.
void	LSEC_clearCompression (LSEC_compression *cpr)
	Clear the compression structrure of any data from a previous cycle.
void	LSEC_deleteCompression (LSEC_compression *cpr)
	Free the memory associated with the compression structure.
unsigned int	LSEC_getBin (LSEC_compression *cpr, unsigned int bin)
	Return the contents of one bin of the histogram.
unsigned int	LSEC_getCount (LSEC_compression *cpr)
	Return the number of non-zero bins in the histogram.
LSEC_compression *	LSEC_newCompression (unsigned int nbits, const char *name)
	Allocate and initialise a new compression structure for APE encoding.
LSEC_compression *	LSEC_newCompressionH (unsigned int nbits, const char *name)
	Allocate and initialise a new compression structure for Huffman encoding.
unsigned int *	LSEC_pack (LSEC_compression *cpr, unsigned *buffer)
	Pack the tables of a compression structure into a buffer.
unsigned int	LSEC_packedSize32 (LSEC_compression *cpr)
	Calculate the size of a packed compression structure.
unsigned	LSEC_process (LSEC_compression *cpr)
	Build the lookup, frequency and probability tables required by the APE.
void	LSEC_reportCompression (LSEC_compression *cmp, FILE *fp)
	Describe the contents of a compression structure.
void	LSEC_zeroBin (LSEC_compression *cpr, unsigned int bin)
	Set the selected bin of the histogram to zero.
unsigned int *	LSEC_encodeCal (LSEC_compaction *cpc, const LSEC_calEvent *event, unsigned int *buf)
	Encode the CAL portion of the event.
unsigned int *	LSEC_encodeTkr (LSEC_compaction *cpc, const EBF_dir *dir, unsigned int *buf)
	Encode the TKR portion of the event.
void	LSEC_eventClear (LSEC_event *evt)
	Clear the stored event data.
LSEC_event *	LSEC_eventCreate (int cap, long long *times)
	Create a new event structure.
void	LSEC_eventDelete (LSEC_event *evt)
	Delete the previously allocated event structure.
unsigned int *	LSEC_eventGet (LSEC_event *evt)
	Get the address of the next stored event.
void	LSEC_eventPrepare (LSEC_event *evt)
	Prepare for a new run.
unsigned	LSEC_eventProcess (LSEC_event *evt, unsigned int edw, EBF_pkt *pkt)
	Process an event packet.
void	LSEC_eventProcSet (LSEC_event *evt, LSEC_eventProcRtn *rtn, void *parm)
	Set the event processing routine to use.
unsigned int *	LSEC_eventPut (LSEC_event *evt)
	Get the address of the next event to store.
void	LSEC_eventRewind (LSEC_event *evt)
	Rewind the event store reading to the beginning.

---

Detailed Description

Definitions for the internal LSEC routines.

Author:

Owen Saxton

$Id: LSEC_p.h,v 1.5 2011/03/27 17:48:19 saxton Exp $

---

Function Documentation

void LSEC_accumCalMeans	(	LSEC_compaction *	cpc,
		unsigned int *	evt,
		EBF_dir *	dir
	)

Accumulate the means of the CAL log end values.

This routine accumulates the CAL ADC values, keeping a separate sum for each log end.

Parameters:

	cpc	Compaction structure
	evt	Pointer to the event storage area
	dir	Pointer to the event to analyse

References LSEC_calCompaction::accum, _LSEC_compaction::cal, LSEC_calCompaction::count, FR_LENG, LM_LENG, LSEC_CAL_M_END, LSEC_CAL_P_END, LSEC_MAX_EVENT_SIZE, LSEC_N_CAL_COL, LSEC_N_CAL_LAY, LSEC_N_LAYCNT_B, LSEC_N_TWR, LSEC_TIM_ACM, setBit(), setNib(), and _LSEC_compaction::times.

Referenced by LSEC_consEventCal().

unsigned LSEC_checkCalCompaction

(

LSEC_compaction *

cpc

)

Check the CAL substructure for errors.

Parameters:

cpc

Pointer to a compaction object

Returns:

The last error from the first substrcture to be found in error or LSEC_SUCCESS if there are no errors.

References _LSEC_compaction::cal, LSEC_calCompaction::logs, LSEC_checkCompression(), LSEC_N_CAL_RNG, LSEC_TIM_CLR, LSEC_calCompaction::means, and _LSEC_compaction::times.

unsigned LSEC_checkCompression

(

LSEC_compression *

cpr

)

Check if there were errors during the histogram or encode operations.

Parameters:

cpr

Pointer to a compression structure

Return values:

	LSEC_SYMOOR	If any of the symbols histogrammed or encoded by this compression structure were out of range
	LSEC_AWEFAIL	If there were any error during the encoding
	LSEC_SUCCESS	If there were no errors

References _LSEC_compression::encerr, _LSEC_compression::name, and _LSEC_compression::ovrflw.

Referenced by LSEC_checkCalCompaction().

void LSEC_clearCalCompaction

(

LSEC_compaction *

cpc

)

Clear away any CAL context from a previous cycle.

Parameters:

cpc

Pointer to a compaction object

References LSEC_calCompaction::accum, _LSEC_compaction::cal, LSEC_calCompaction::count, LSEC_calCompaction::cSize, LSEC_calCompaction::etx, LSEC_calCompaction::logs, LSEC_clearCompression(), LSEC_N_CAL_RNG, LSEC_TIM_CLR, LSEC_calCompaction::means, and _LSEC_compaction::times.

Referenced by LSEC_consPrepare().

void LSEC_clearCompression

(

LSEC_compression *

cpr

)

Clear the compression structrure of any data from a previous cycle.

Parameters:

cpr

Pointer to an allocated, initialised, compression structure

References LSEC_compressionDesc::count, _LSEC_compression::desc, _LSEC_compression::encerr, LSEC_compressionDesc::first_bin, _LSEC_compression::hist, _LSEC_compression::last_bin, _LSEC_compression::nbits, and _LSEC_compression::ovrflw.

Referenced by LSEC_clearCalCompaction().

LSEC_consignment* LSEC_consCreate	(	unsigned	cpuid,
		unsigned	srcid,
		unsigned	cap,
		LSEC_compaction *	cpc,
		LSEC_event *	evt,
		long long *	times
	)

Create a new consignment.

This routine allocates memory for a consigment structure and its associated data structures, and initialises it.

Parameters:

	srcid	ID of the data source
	cpuid	ID of the CPU the calibration is being run on
	cap	The capacity (in events) of the consignment
	cpc	Pointer to the compaction state information
	evt	Pointer to the event store
	times	Pointer to the processing times array.

Returns:

Pointer to an allocated, initialised consignment (NULL if there is an error allocating memory)

References _LSEC_consignment::acdFw, _LSEC_consignment::buf, _LSEC_consignment::calFw, _LSEC_consignment::cpc, _LSEC_consignment::ctx, _LSEC_consignment::evt, _LSEC_consignment::fpa, LSEC_consDelete(), LSEC_ID_CALIB_ACD, LSEC_ID_CALIB_CAL, LSEC_ID_CALIB_TKR, _LSEC_consignment::sentSem, _LSEC_consignment::times, and _LSEC_consignment::tkrFw.

Referenced by LSEC_initialize().

LSEC_ctx* LSEC_consCtxGet

(

LSEC_consignment *

cns

)

Get the address of the context structure.

Parameters:

cns

Pointer to the consignment structure

Returns:

The address of the context structure

References _LSEC_consignment::ctx.

Referenced by LSEC_getCtx(), and LSEC_initialize().

void LSEC_consDelete

(

LSEC_consignment *

cns

)

Free the previously allocated consignment structure.

Parameters:

cns

Pointer to allocated, intialised consignment structure

References _LSEC_consignment::acdFw, _LSEC_consignment::buf, _LSEC_consignment::calFw, _LSEC_consignment::ctx, _LSEC_consignment::fpa, _LSEC_consignment::sentSem, and _LSEC_consignment::tkrFw.

Referenced by LSEC_consCreate(), and LSEC_terminate().

unsigned LSEC_consEventCal	(	void *	parm,
		EBF_dir *	dir
	)

Process a compressed CAL event.

This routine starts the process by accumulating data for the CAL means calculation.

Parameters:

	parm	Pointer to the consignment structure
	dir	Pointer to the event directory

Return values:

LSEC_SUCCESS

Success (always)

References _LSEC_consignment::cpc, _LSEC_consignment::evt, LSEC_accumCalMeans(), and LSEC_eventPut().

Referenced by LSEC_initRun().

unsigned LSEC_consEventImm	(	void *	parm,
		EBF_dir *	dir
	)

Process an event immediately.

This routine is used to pass an event immediately to the datagram framework. It is used in all cases except compressed CAL events.

Parameters:

	parm	Pointer to the consignment structure
	dir	Pointer to the event directory

Return values:

	LSEC_SUCCESS	Success
	LSEC_OVERSIZE	Event too large for a datagram

References _LSEC_consignment::evtErr, and _LSEC_consignment::fw.

Referenced by LSEC_initRun().

void LSEC_consPrepare	(	LSEC_consignment *	cns,
		unsigned	runid,
		unsigned	mode,
		LSEC_compLevel	comp
	)

Prepare for a new calibration run.

This routine sets the runid and start time for the first datagram of a new calibration, as well as several other mode-dependent parameters.

Parameters:

	cns	Pointer to allocated, intialised consignment structure
	runid	32-bit number identifying the calibration run
	mode	The calibration mode (ACD, CAL or TKR)
	comp	The compression level (normal, only, none)

References _LSEC_consignment::acdFw, _LSEC_consignment::calFw, _LSEC_consignment::comp, _LSEC_consignment::consign, _LSEC_consignment::cpc, _LSEC_consignment::ctxId, _LSEC_consignment::ctxSize, _LSEC_consignment::dgmQued, _LSEC_consignment::dgmSent, _LSEC_consignment::fw, LSEC_clearCalCompaction(), LSEC_COMP_NONE, LSEC_COMP_NORM, LSEC_COMP_ONLY, LSEC_ID_CALIB_ACD_CTX, LSEC_ID_CALIB_CAL_CTX, LSEC_ID_CALIB_TKR_CTX, and _LSEC_consignment::tkrFw.

Referenced by LSEC_initRun().

unsigned LSEC_consProcess

(

LSEC_consignment *

cns

)

Process a consignment.

Parameters:

cns

Pointer to a consignment structure

Return values:

LSEC_SUCCESS

If all goes well

References _LSEC_consignment::comp, _LSEC_consignment::consign, _LSEC_consignment::dgmQued, _LSEC_consignment::dgmSent, _LSEC_consignment::fw, LSEC_COMP_NORM, LSEC_TIM_SND, _LSEC_consignment::reason, _LSEC_consignment::sentSem, and _LSEC_consignment::times.

Referenced by LSEC_consign().

void LSEC_consReason	(	LSEC_consignment *	cns,
		int	reason
	)

Set the current datagram close reason.

Parameters:

	cns	Pointer to the consignment structure
	reason	The reason code to be set

References _LSEC_consignment::reason.

Referenced by LSEC_setReason().

unsigned int* LSEC_copyUser	(	LSEC_compaction *	cpc,
		unsigned int *	buf
	)

Copy datagram header information into the buffer.

Parameters:

	buf	Pointer to the buffer where the context should be placed
	cpc	Pointer to the structure containing the tables (a compaction)

Returns:

Pointer to the next output location to be filled.

References _LSEC_compaction::copyUser.

void LSEC_deleteCompaction

(

LSEC_compaction *

cpc

)

Free memory previously allocated with a call to LSEC_newCompaction.

Parameters:

cpc

Pointer to a compaction structure previously created by a call to LSEC_newCompaction

References _LSEC_compaction::cal, LSEC_calCompaction::cData, LSEC_calCompaction::logs, LSEC_deleteCompression(), LSEC_N_CAL_RNG, and LSEC_calCompaction::means.

Referenced by LSEC_newCompaction(), and LSEC_terminate().

void LSEC_deleteCompression

(

LSEC_compression *

cpr

)

Free the memory associated with the compression structure.

Parameters:

cpr

Pointer to an allocated compression structure

Referenced by LSEC_deleteCompaction().

unsigned int* LSEC_encodeCal	(	LSEC_compaction *	cpc,
		const LSEC_calEvent *	event,
		unsigned int *	buf
	)

Encode the CAL portion of the event.

Parameters:

	cpc	Compaction structure
	event	Pointer to the saved event
	buf	Pointer to the buffer receiving the encoded data

Returns:

Address of the word after the encoded data

References _LSEC_compaction::cal, _LSEC_calEvent::dgnMap, _LSEC_calEvent::diag, FR_LENG, _LSEC_calEvent::frstRng, _LSEC_calEvent::gem, getBit(), getNib(), LM_LENG, _LSEC_calEvent::logMap, LSEC_calCompaction::logs, LSEC_CAL_M_END, LSEC_CAL_P_END, LSEC_compressH(), LSEC_N_CAL_COL, LSEC_N_CAL_LAY, LSEC_N_TWR, _LSEC_calEvent::size, and _LSEC_calEvent::twrMap.

unsigned int* LSEC_encodeTkr	(	LSEC_compaction *	cpc,
		const EBF_dir *	dir,
		unsigned int *	buf
	)

Encode the TKR portion of the event.

Parameters:

	cpc	Compaction structure
	dir	Pointer to the event directory
	buf	Pointer to the buffer receiving the encoded data

Returns:

Address of the word after the encoded data

References LSEC_tkr::channel, _LSEC_compaction::ctx, LSEC_channel::flags, LSEC_N_TKR_CC, LSEC_N_TKR_CHNL, LSEC_N_TKR_FE, LSEC_N_TKR_RC, LSEC_N_TWR, LSEC_channel::number, LSEC_ctx::specific, and LSEC_specific::tkr.

void LSEC_eventClear

(

LSEC_event *

evt

)

Clear the stored event data.

Parameters:

evt

Pointer to an event structure.

References _LSEC_event::dir, _LSEC_event::read, _LSEC_event::start, and _LSEC_event::write.

Referenced by LSEC_clearEvent().

LSEC_event* LSEC_eventCreate	(	int	cap,
		long long *	times
	)

Create a new event structure.

Parameters:

	cap	The maximum number of events that can be stored.
	times	Address of the processing times array.

Returns:

A pointer to the new event structure, or NULL if there is insufficient memory available.

References _LSEC_event::blksz, _LSEC_event::end, LSEC_eventDelete(), LSEC_MAX_EVENT_SIZE, MAX_OVERHEAD_PER_EVENT, _LSEC_event::read, _LSEC_event::siv, _LSEC_event::start, _LSEC_event::times, and _LSEC_event::write.

Referenced by LSEC_initialize().

void LSEC_eventDelete

(

LSEC_event *

evt

)

Delete the previously allocated event structure.

Parameters:

evt

Pointer to allocated, intialised event structure

References _LSEC_event::start.

Referenced by LSEC_eventCreate(), and LSEC_terminate().

unsigned int* LSEC_eventGet

(

LSEC_event *

evt

)

Get the address of the next stored event.

This routine return a pointer to the next event and advances the read pointer.

Parameters:

evt

Pointer to an event structure

Returns:

Pointer to the next event, or NULL if there are no more events.

References _LSEC_event::blksz, _LSEC_event::read, and _LSEC_event::write.

void LSEC_eventPrepare

(

LSEC_event *

evt

)

Prepare for a new run.

Parameters:

evt

Pointer to allocated, intialised event structure

References _LSEC_event::count.

Referenced by LSEC_initRun().

unsigned LSEC_eventProcess	(	LSEC_event *	evt,
		unsigned int	edw,
		EBF_pkt *	pkt
	)

Process an event packet.

This routine is called whenever a new event packet arrives.

Parameters:

	evt	Pointer to an event structure
	edw	Description of the event (a thirty-two bit number that indicates, among other things, errors in the event transmission)
	pkt	Pointer to the event packet

Returns:

The OR of zero or more of the bits:

• LSEC_EVT_FREE Free the packet
• LSEC_EVT_DONE Event is complete

References _LSEC_event::count, _LSEC_event::dir, LSEC_EVT_DONE, LSEC_TIM_EVT, _LSEC_event::procParm, _LSEC_event::procRtn, _LSEC_event::siv, and _LSEC_event::times.

Referenced by LSEC_processEvent().

void LSEC_eventProcSet	(	LSEC_event *	evt,
		LSEC_eventProcRtn *	rtn,
		void *	parm
	)

Set the event processing routine to use.

Parameters:

	evt	Pointer to an event structure.
	rtn	Pointer to the processing routine.
	parm	Parameter to pass to the processing routine.

References _LSEC_event::procParm, and _LSEC_event::procRtn.

Referenced by LSEC_initRun().

unsigned int* LSEC_eventPut

(

LSEC_event *

evt

)

Get the address of the next event to store.

This routine return a pointer to the next event that can be stored and advances the write pointer.

Parameters:

evt

Pointer to an event structure

Returns:

Pointer to the next event to store, or NULL if the storage area is filled to capacity.

References _LSEC_event::blksz, _LSEC_event::end, and _LSEC_event::write.

Referenced by LSEC_consEventCal().

void LSEC_eventRewind

(

LSEC_event *

evt

)

Rewind the event store reading to the beginning.

Parameters:

evt

Pointer to an event structure.

References _LSEC_event::read, and _LSEC_event::start.

unsigned int LSEC_eventSizeCal

(

const LSEC_calEvent *

event

)

Get the size of a saved CAL event.

Parameters:

event

Pointer to a CAL event data structure.

Returns:

The size, in words, of the saved event. A non-zero value means that the event is in raw format. A zero value means that the event has been expanded and its final size is not known.

EBF_ctb* LSEC_gemContribCal

(

const LSEC_calEvent *

event

)

Get the GEM contribution address from a saved CAL event.

Parameters:

event

Pointer to a CAL event data structure.

Returns:

The address of the saved GEM contribution.

unsigned int LSEC_getBin	(	LSEC_compression *	cpr,
		unsigned int	bin
	)

Return the contents of one bin of the histogram.

Parameters:

	cpr	Pointer to an allocated, initialised, populated, compression structure
	bin	ID of one of the bins of the histogram

Returns:

Contents of the bin

References _LSEC_compression::hist, and _LSEC_compression::nbits.

unsigned int LSEC_getCount

(

LSEC_compression *

cpr

)

Return the number of non-zero bins in the histogram.

Parameters:

cpr

Pointer to a compression structure

Returns:

Number of non-zero bins in the histogram

References LSEC_compressionDesc::count, and _LSEC_compression::desc.

void LSEC_histoCalMeans

(

LSEC_compaction *

cpc

)

Calculate and histogram the mean values for the CAL log ends.

The mean ADC values for each CAL log end are calculated and histogrammed, one histogram per range, ready for being encoded.

Parameters:

cpc

Pointer to an LSEC_compaction structure

References LSEC_calCompaction::accum, _LSEC_compaction::cal, LSEC_calCompaction::count, LSEC_histogram(), LSEC_N_CAL_COL, LSEC_N_CAL_END, LSEC_N_CAL_LAY, LSEC_N_CAL_RNG, LSEC_N_TWR, LSEC_TIM_HST, LSEC_calCompaction::means, and _LSEC_compaction::times.

void LSEC_histogramCal	(	LSEC_compaction *	cpc,
		LSEC_calEvent *	event
	)

Perform histogramming of the CAL data.

Several quantities associated with the CAL are histogrammed in preparation for being encoded. These include: the tower map; the mean-subtracted ADC values, offset to be positive, and grouped by range; the diagnostic tower map; and the diagnostic data.

Parameters:

	cpc	Compaction structure
	event	Pointer to the stored event

References LSEC_calCompaction::accum, _LSEC_compaction::cal, FR_LENG, getBit(), getNib(), LM_LENG, LSEC_calCompaction::logs, LSEC_CAL_M_END, LSEC_CAL_P_END, LSEC_histogramH(), LSEC_N_CAL_COL, LSEC_N_CAL_LAY, LSEC_N_TWR, LSEC_TIM_HST, _LSEC_calEvent::size, _LSEC_compaction::times, and _LSEC_calEvent::twrMap.

LSEC_compaction* LSEC_newCompaction	(	unsigned	cap,
		long long *	times
	)

Allocate memory for an LSEC_compaction structure and all the substructures.

Parameters:

	cap	Capacity of the calibration task, the maximum number of events that can be collected each cycle
	times	Pointer to the array of processing times.

Returns:

Pointer to an allocated, initialise, LSEC_compaction structure

References _LSEC_compaction::cal, LSEC_calCompaction::cData, LSEC_calCompaction::cMax, LSEC_calCompaction::logs, LSEC_deleteCompaction(), LSEC_MAX_EVENT_SIZE, LSEC_N_CAL_RNG, LSEC_N_LOG_BITS, LSEC_newCompression(), LSEC_newCompressionH(), LSEC_calCompaction::means, and _LSEC_compaction::times.

Referenced by LSEC_initialize().

LSEC_compression* LSEC_newCompression	(	unsigned int	nbits,
		const char *	name
	)

Allocate and initialise a new compression structure for APE encoding.

Parameters:

	nbits	Number of symbols in the complete range of possible symbols (including excluded internal sub-ranges), hence the number of bins in the histogram and frequency tables
	name	String used in the reporting of error to identify a compression structure

Returns:

Pointer to an allocated and initialised LSEC_compression structure

The order of calling the functions presented here should be LSEC_newCompression LSEC_histogram - Repeat as necessary LSEC_process LSEC_pack LSEC_compress - Repeat as necessary LSEC_clearCompression : repeat as necessary : LSEC_deleteCompression

References _LSEC_compression::delta, _LSEC_compression::freq, _LSEC_compression::fwlu, _LSEC_compression::hist, _LSEC_compression::mask, _LSEC_compression::name, _LSEC_compression::nbits, and _LSEC_compression::table.

Referenced by LSEC_newCompaction().

LSEC_compression* LSEC_newCompressionH	(	unsigned int	nbits,
		const char *	name
	)

Allocate and initialise a new compression structure for Huffman encoding.

Parameters:

	nbits	Number of symbols in the complete range of possible symbols (including excluded internal sub-ranges), hence the number of bins in the histogram and frequency tables
	name	String used in the reporting of error to identify a compression structure

Returns:

Pointer to an allocated and initialised LSEC_compression structure

The order of calling the functions presented here should be LSEC_newCompression LSEC_histogram - Repeat as necessary LSEC_process LSEC_pack LSEC_compress - Repeat as necessary LSEC_clearCompression : repeat as necessary : LSEC_deleteCompression

References _LSEC_compression::hde, _LSEC_compression::hist, _LSEC_compression::hist0, _LSEC_compression::mask, _LSEC_compression::name, and _LSEC_compression::nbits.

Referenced by LSEC_newCompaction().

unsigned int* LSEC_pack	(	LSEC_compression *	cpr,
		unsigned *	buffer
	)

Pack the tables of a compression structure into a buffer.

This routine selects sufficient data from the tables of the compression structure to be able to recreate the tables required to decompress the data, and pack it into the consignment

Parameters:

	buffer	Pointer to the start of the buffer to place the packed structure
	cpr	Pointer to an initialised, populated and processed compression structure

Returns:

Pointer to the word after this compression structure after packing

References LSEC_compressionDesc::count, _LSEC_compression::delta, _LSEC_compression::desc, _LSEC_compression::freq, _LSEC_compression::hde, LSEC_compressionDesc::n_delta_bits, and LSEC_compressionDesc::n_entry_bits.

unsigned int LSEC_packedSize32

(

LSEC_compression *

cpr

)

Calculate the size of a packed compression structure.

This routine calculates the number of 32-bit words required to hold the packed compression structure

Parameters:

cpr

Pointer to a compression structure

Returns:

Size of the packed compression structure

References LSEC_compressionDesc::count, _LSEC_compression::desc, _LSEC_compression::hde, LSEC_compressionDesc::n_delta_bits, and LSEC_compressionDesc::n_entry_bits.

unsigned LSEC_process

(

LSEC_compression *

cpr

)

Build the lookup, frequency and probability tables required by the APE.

Parameters:

cpr

Pointer to an allocated, initialised, populated, compression structure

Return values:

LSEC_SUCCESS

If the processing goes well

References LSEC_compressionDesc::count, _LSEC_compression::delta, _LSEC_compression::desc, LSEC_compressionDesc::first_bin, _LSEC_compression::freq, _LSEC_compression::fwlu, _LSEC_compression::hde, _LSEC_compression::hist, _LSEC_compression::hist0, _LSEC_compression::last_bin, LSEC_compressionDesc::n_delta_bits, LSEC_compressionDesc::n_entry_bits, _LSEC_compression::nbits, and _LSEC_compression::table.

Referenced by LSEC_processCal().

unsigned LSEC_processCal

(

LSEC_compaction *

cpc

)

Process the CAL compression structures.

Parameters:

cpc

Pointer to an LSEC_compaction structure

References _LSEC_compaction::cal, LSEC_calCompaction::logs, LSEC_process(), LSEC_TIM_HST, LSEC_calCompaction::means, and _LSEC_compaction::times.

void LSEC_reportCalCompaction	(	LSEC_compaction *	cpc,
		FILE *	fp
	)

Write CAL compression table contents to an ASCII file.

Parameters:

	cpc	Pointer to a compaction object
	fp	Pointer to the destination file

References _LSEC_compaction::cal, LSEC_calCompaction::logs, LSEC_N_CAL_RNG, LSEC_reportCompression(), and LSEC_calCompaction::means.

void LSEC_reportCompression	(	LSEC_compression *	cpr,
		FILE *	fp
	)

Describe the contents of a compression structure.

This routine formats the compression structure as ASCII text and writes it to the specified file

Parameters:

	cpr	Pointer to the compression structure
	fp	Pointer to the file used as the destination

References LSEC_compressionDesc::count, _LSEC_compression::desc, _LSEC_compression::encerr, _LSEC_compression::freq, _LSEC_compression::hist, _LSEC_compression::name, _LSEC_compression::nbits, and _LSEC_compression::ovrflw.

Referenced by LSEC_reportCalCompaction().

void LSEC_setContext	(	LSEC_compaction *	cpc,
		const LSEC_ctx *	ctx
	)

Set the context information pointer.

Parameters:

	cpc	Pointer to a compaction structure
	ctx	Pointer to the context block

References _LSEC_compaction::ctx.

Referenced by LSEC_initialize().

void LSEC_setMode	(	LSEC_compaction *	cpc,
		unsigned	mode
	)

Set the calibration mode.

Parameters:

	cpc	Pointer to a compaction structure
	mode	The calibration mode

References _LSEC_compaction::copyUser, and _LSEC_compaction::sizeUser.

Referenced by LSEC_initRun().

unsigned int LSEC_sizeofUser

(

LSEC_compaction *

cpc

)

Calculate the number of 32-bit words required to hold the tables against which the contributions will be encoded.

Parameters:

cpc

Pointer to the compaction structure

Returns:

Number of 32-bit words required to hold the packed tables used to encode the contribution

References _LSEC_compaction::sizeUser.

void LSEC_zeroBin	(	LSEC_compression *	cpr,
		unsigned int	bin
	)

Set the selected bin of the histogram to zero.

This indicates that this symbol will be selectively removed from the uncompressed data stream before encoding

Parameters:

	cpr	Pointer to an allocated, initialised, populated, compression structure
	bin	ID of one of the bins of the histogram

References _LSEC_compression::hist, and _LSEC_compression::nbits.