LSD_sdi.c File Reference

Generic formatting of an LSD data structure (LSF datagram encapsulated in CCSDS packet) and writing to SDI. More...

#include <EMP/LSD_sdi.h>
#include <LSF/LSF.h>
#include <ITC/ITC_pubdefs.h>
#include <IMM/RBM_pubdefs.h>
#include <CCSDS/CCSDS_pkt.h>
#include <PBS/SEM.h>
#include <dprintf.h>
#include <stdio.h>

Classes

struct _LSD_sdiPds

struct _LSD_sdi

Context structure for formatting and writing data to the SDI. More...

Defines

#define DEBUG

#define RBM_PRINT(_op, _status, _ptr, _len)

Debugging macro to print the result of an RBM operation.

#define RND_TO(_v, _r) ((((int)(_v)) + (_r) - 1) & ~((_r) - 1))

Round a value, _v up to a binary power of two boundary, _r.

Typedefs

typedef struct _LSD_sdiPds LSD_sdiPds

typedef struct _LSD_sdi LSD_sdi

Functions

static void sdiDone (ITC_QueueItem *qitem, unsigned int status, LSD_sdi *sdi, LSD_sdiPds *pds, void *prm2, unsigned int tx)

Callback indicating the physical IO to the SDI has completed.

static __inline RBM_Ring * sdiRingConstruct (int buf_size, int overflow)

Creates an RBM-style ring buffer.

unsigned int LSD_sdiSizeof (void)

Returns the size, in bytes of LSD_sdi context handle.

unsigned int LSD_sdiConstruct (LSD_sdi *sdi, int apid, int ringSize, int ringOverflow, LSD_sdiWriteRtn writeRtn, void *writePrm)

Creates an instance of an LSD_sdi stream.

LSD_sdiPds * LSD_sdiGetW (LSD_sdi *sdi, int dgmSize, unsigned int ts_secs, unsigned int ts_usecs)

Allocate and fill a packet for SDI, except for payload.

unsigned int LSD_sdiShrink (LSD_sdi *sdi, LSD_sdiPds *pds, int shrinkSize)

Shrink the allocation of the created packet for changes in the payload length.

unsigned int LSD_sdiSend (LSD_sdi *sdi, LSD_sdiPds *pds)

Send out filled-in packet to the SDI.

unsigned int LSD_sdiWrite (void *prm, LSD_sdiPds *pds)

Default routine to send completed queue item to the ITC queue.

void LSD_sdiDestruct (LSD_sdi *sdi)

Destroy the SDI context.

unsigned int LSD_sdiPdsLenGet (LSD_sdiPds *pds)

Access function to return the length, in bytes, of the packet This includes the CCSDS header.

void * LSD_sdiPdsCcsdsGet (LSD_sdiPds *pds)

Access function to return a pointer to CCSDS header.

LSF_datagram * LSD_sdiPdsDgmGet (LSD_sdiPds *pds)

Access function to return a pointer to LSF datagram header.

Detailed Description

Generic formatting of an LSD data structure (LSF datagram encapsulated in CCSDS packet) and writing to SDI.

Author:: JJRussell - russell@slac.stanford.edu


   CVS $Id: LSD_sdi.c,v 1.6 2011/03/26 20:07:42 russell Exp $

Generic formatting of an LSD data structure (LSF datagram encapsulated in CCSDS packet) and writing to SDI. Provision is made to substitute the physical write to the SDI with a user supplied routine. This allows one to dump the data to a file for a host platform.

Define Documentation

#define RBM_PRINT	(	_op,
		_status,
		_ptr,
		_len	)

Value:

DPRINTF ("RBM_" _op ": status=0x%08x  ptr:0x%08x: len=%04x\n",    \
                 _status, _ptr, _len)

Debugging macro to print the result of an RBM operation.

Parameters:

	_op	6-letter string giving the operation (alloc, free, shrink).
	_status	The completion status of the operation.
	_ptr	The pointer allocated, freeed or shrank-to.
	_len	The number of bytes of this operation

This could easily be put directly into the code, but this ensures uniformity of formatting, resulting in easier to read output; always important during those highly stressful debugging times when this macro is sure to see action.

Referenced by LSD_sdiGetW(), LSD_sdiShrink(), and sdiDone().

#define RND_TO	(	_v,
		_r		)	((((int)(_v)) + (_r) - 1) & ~((_r) - 1))

Round a value, _v up to a binary power of two boundary, _r.

Returns:: The rounded value

Parameters:

	_v	The value to round
	_r	The binary power of 2 boundary to round to, i.e. r = 2, 4, 8, etc

Function Documentation

unsigned int LSD_sdiConstruct	(	LSD_sdi *	sdi,
		int	apid,
		int	ringSize,
		int	ringOverflow,
		LSD_sdiWriteRtn	writeRtn,
		void *	writePrm
	)

Creates an instance of an LSD_sdi stream.

Return values:

	0,Success
	-1,Failed	to create the RBM ring buffer

Parameters:

	sdi	The LSD_sdi context handle to construct
	apid	The CCSDS APID to associate with this stream. Due to the single threaded nature of the SDI, a stream can only control one APID at a time
	ringSize	Size, in bytes, of the ring buffer to create
	ringOverflow	Size, in bytes, of the amount to be reserved from ringSize as an overflow buffer. This must be less than ringSize.
	writeRtn	The routine to perform the physical write. If NULL is specified, the default routine, LSD_sdiWrite is used.
	writePrm	The parameter to pass to the write routine. This parameter is irrelevant if writeRtn is specified as NULL.

References _LSD_sdi::apid, _LSD_sdi::ccsdsHdrSize, LSD_sdiWrite(), _LSD_sdi::pool, _LSD_sdiWriteCbp::prm, _LSD_sdi::qitemHdrSize, RND_TO, _LSD_sdiWriteCbp::rtn, sdiRingConstruct(), _LSD_sdi::semaphore, and _LSD_sdi::write.

Referenced by AscEdsConstruct().

void LSD_sdiDestruct ( LSD_sdi * sdi )

Destroy the SDI context.

Parameters:

sdi

The LSD SDI context handle to destroy

References _LSD_sdi::pool, and _LSD_sdi::semaphore.

Referenced by AscEdsDestruct().

LSD_sdiPds* LSD_sdiGetW	(	LSD_sdi *	sdi,
		int	dgmSize,
		unsigned int	ts_secs,
		unsigned int	ts_usecs
	)

Allocate and fill a packet for SDI, except for payload.

Returns:: The allocated pointer or NULL on failure

Parameters:

	sdi	The LSD SDI context handler
	dgmSize	Size of the datagram (including any headers)
	ts_secs	The seconds part of the timestamp to associate with this datagram
	ts_usecs	The useconds part of the timestamp to associate with this datagram

Note:: The allocations are of the wait variety. This means that one should not use this call when waiting for a resource to free is not allowed.
The only 2 failure modes, allocation failure and unable to format the CCSDS header are both likely due a memory corruption. Recovery is unlikely. The correct response should likely be to bugcheck.

References _LSD_sdi::apid, _LSD_sdi::ccsdsHdrSize, _LSD_sdi::pool, _LSD_sdi::qitemHdrSize, and RBM_PRINT.

Referenced by output().

void* LSD_sdiPdsCcsdsGet ( LSD_sdiPds * pds )

Access function to return a pointer to CCSDS header.

Returns:: Pointer to the CCSDS header

Parameters:

pds

The packet descriptor

LSF_datagram* LSD_sdiPdsDgmGet ( LSD_sdiPds * pds )

Access function to return a pointer to LSF datagram header.

Returns:: Pointer to the datagram header

Parameters:

pds

The packet descriptor

Referenced by output().

unsigned int LSD_sdiPdsLenGet ( LSD_sdiPds * pds )

Access function to return the length, in bytes, of the packet This includes the CCSDS header.

Returns:: the length, in bytes, of the packet; includes the length of the CCSDS header plus the datagram itself

Parameters:

pds

The packet descriptor

unsigned int LSD_sdiSend	(	LSD_sdi *	sdi,
		LSD_sdiPds *	pds
	)

Send out filled-in packet to the SDI.

Returns:: status

Parameters:

	sdi	The LSD SDI context handler
	pds	The packet descriptor structure

References _LSD_sdi::ccsdsHdrSize, _LSD_sdiWriteCbp::prm, _LSD_sdiWriteCbp::rtn, sdiDone(), and _LSD_sdi::write.

Referenced by output().

unsigned int LSD_sdiShrink	(	LSD_sdi *	sdi,
		LSD_sdiPds *	pds,
		int	shrinkSize
	)

Shrink the allocation of the created packet for changes in the payload length.

Returns:: Status, currently the status of RBM shrink operation

Parameters:

	sdi	The LSD SDI context handler
	pds	The packet descriptor structure
	shrinkSize	The amount, in bytes, to shrink

References _LSD_sdi::pool, and RBM_PRINT.

Referenced by output().

unsigned int LSD_sdiSizeof ( void )

Returns the size, in bytes of LSD_sdi context handle.

Returns:: The size, in bytes of LSD_sdi context handle

Referenced by AscEdsConstruct().

unsigned int LSD_sdiWrite	(	void *	prm,
		LSD_sdiPds *	pds
	)

Default routine to send completed queue item to the ITC queue.

Returns:: Status

Parameters:

	prm	User context parameter
	pds	The packet descriptor

Referenced by LSD_sdiConstruct().

static void sdiDone	(	ITC_QueueItem *	qitem,
		unsigned int	status,
		LSD_sdi *	sdi,
		LSD_sdiPds *	pds,
		void *	prm2,
		unsigned int	tx
	)			`[static]`

Callback indicating the physical IO to the SDI has completed.

Parameters:

	qitem	The ITC Que item that was sent.
	status	The status of the transaction (unused).
	sdi	The LSD SDI context handle
	pds	The packet descriptor structure. This is the pointer that should be freed back to RBM and the length is carried in the pds.
	prm2	Unused.
	tx	Flag indicating whether this is being called back in the context of the transmission task or the user's output routine. This dictates whether the memory is returned via an RBM_free or RBM_shrink.

References _LSD_sdi::pool, and RBM_PRINT.

Referenced by LSD_sdiSend().

static __inline RBM_Ring * sdiRingConstruct	(	int	buf_size,
		int	overflow
	)			`[static]`

Creates an RBM-style ring buffer.

Returns:: On success, the handle to the create RBM ring buffer, On failure, NULL

Parameters:

	buf_size	The size, in bytes, of the RBM ring buffer. This is includes the size of the overflow region, meaning that buf_size must > overflow
	overflow	The size, in bytes, of the overflow region. This should be as large as the largest allocation that will be done

Referenced by LSD_sdiConstruct().


Classes
struct	_LSD_sdiPds
struct	_LSD_sdi
	Context structure for formatting and writing data to the SDI. More...
Defines
#define	DEBUG
#define	RBM_PRINT(_op, _status, _ptr, _len)
	Debugging macro to print the result of an RBM operation.
#define	RND_TO(_v, _r) ((((int)(_v)) + (_r) - 1) & ~((_r) - 1))
	Round a value, _v up to a binary power of two boundary, _r.
Typedefs
typedef struct _LSD_sdiPds	LSD_sdiPds
typedef struct _LSD_sdi	LSD_sdi
Functions
static void	sdiDone (ITC_QueueItem qitem, unsigned int status, LSD_sdi sdi, LSD_sdiPds pds, void prm2, unsigned int tx)
	Callback indicating the physical IO to the SDI has completed.
static __inline RBM_Ring *	sdiRingConstruct (int buf_size, int overflow)
	Creates an RBM-style ring buffer.
unsigned int	LSD_sdiSizeof (void)
	Returns the size, in bytes of LSD_sdi context handle.
unsigned int	LSD_sdiConstruct (LSD_sdi sdi, int apid, int ringSize, int ringOverflow, LSD_sdiWriteRtn writeRtn, void writePrm)
	Creates an instance of an LSD_sdi stream.
LSD_sdiPds *	LSD_sdiGetW (LSD_sdi *sdi, int dgmSize, unsigned int ts_secs, unsigned int ts_usecs)
	Allocate and fill a packet for SDI, except for payload.
unsigned int	LSD_sdiShrink (LSD_sdi sdi, LSD_sdiPds pds, int shrinkSize)
	Shrink the allocation of the created packet for changes in the payload length.
unsigned int	LSD_sdiSend (LSD_sdi sdi, LSD_sdiPds pds)
	Send out filled-in packet to the SDI.
unsigned int	LSD_sdiWrite (void prm, LSD_sdiPds pds)
	Default routine to send completed queue item to the ITC queue.
void	LSD_sdiDestruct (LSD_sdi *sdi)
	Destroy the SDI context.
unsigned int	LSD_sdiPdsLenGet (LSD_sdiPds *pds)
	Access function to return the length, in bytes, of the packet This includes the CCSDS header.
void *	LSD_sdiPdsCcsdsGet (LSD_sdiPds *pds)
	Access function to return a pointer to CCSDS header.
LSF_datagram *	LSD_sdiPdsDgmGet (LSD_sdiPds *pds)
	Access function to return a pointer to LSF datagram header.