CCSDS_istream.c File Reference

Input CCSDS packets. More...

#include <QSD/CCSDS_istream.h>
#include <QSD/CCSDS_apidDsc.h>
#include <QSD/CCSDS_telemetry.h>
#include <PBI/Endianness.h>
#include <stdlib.h>
#include <stdio.h>
#include <errno.h>
#include <QSD/CCSDS_telemetryPrint.h>

Classes
struct	_CCSDS_istreamInput
	Function callbacks to read and close an input stream. More...
struct	_CCSDS_istream
	The control structure/context for reading a CCSDS formatted stream of bytes. More...
Defines
#define	CCSDS_M_SEQ   0x3fff
	Mask of the valid bits in the CCSDS sequence number.
Typedefs
typedef struct _CCSDS_istreamInput	CCSDS_istreamInput
	Typedef for struct _CCSDS_istreamInput.
Functions
static int __inline	form_transition (unsigned int siv, unsigned short int flags)
	Forms the new state transition word. This consists of 2 bits defining the previous packet state (ONLY, FIRST, MIDDLE, LAST) and 2 bits defining the current packet state.
static int __inline	check_transition (unsigned int state)
	Checks that the transition from the previous state to the current state is allowed.
static void	report_siv_error (int siv, int apid, int seq)
	Reports the reasons for CCSDS siv errors.
static int	file_read (FILE *file, unsigned char *buf, int nbytes, int sbytes)
	Simple routine to do a file read using fread.
static CCSDS_istream *	construct (CCSDS_istream *istream, int free)
	Construct for a newly minted CCSDS_istream structure.
static __inline unsigned int	check_sequencing (unsigned int siv, unsigned short int flags, unsigned short int prv_seq, unsigned short int sequence)
	Checks that both the packet transition from the previous state to the current state is allowed and that the sequence number advances correctly. Note that this routine only checks the integrity, it does not update any state information.
int	CCSDS_istreamSizeof (void)
	Returns the size, in bytes, of a CCSDS_istream structure.
CCSDS_istream *	CCSDS_istreamNew (void)
	Convenience function to allocate and initialize a CCSDS_istream control structure.
int	CCSDS_istreamConstruct (CCSDS_istream *istream)
	Constructs (initializes) a previously uninitialized CCSDS_istream control structure.
int	CCSDS_istreamConnect (CCSDS_istream *istream, void *prm, CCSDS_istreamReader read, CCSDS_istreamCloser close, CCSDS_istreamTeller tell)
	Connects a read mechanism with the specified stream.
int	CCSDS_istreamHdrRead (CCSDS_istream *istream, CCSDS_telemetry *packet)
	Reads the CCSDS header.
int	CCSDS_istreamDatAdvance (CCSDS_istream *istream, CCSDS_telemetry const *packet, CCSDS_apidDsc *dsc)
	Advances past the current CCSDS data payload with reading the data into the buffer. All integrity checks are preformed. This in contrast with calling CCSDS_istreamDatRead with a NULL descriptor.
int	CCSDS_istreamDatRead (CCSDS_istream *istream, CCSDS_telemetry const *packet, CCSDS_apidDsc *dsc)
	Reads the current CCSDS data payload into the buffer specified by dsc.
int	CCSDS_istreamPktCheck (unsigned int opts, CCSDS_istream *istream, CCSDS_telemetry const *pkt, CCSDS_apidDsc *dsc)
	Precanned CCSDS_istreamProcess callback routine to check the integrity of a CCSDS packet.
int	CCSDS_istreamPktResynch (CCSDS_istream *istream, CCSDS_telemetry const *packet, CCSDS_apidDsc *dsc)
	Routine to recover from an APID sequence number or sequence state (first, middle, last) packet error. It can be used part of the CCSDS_istreamProcess packer checker routine.
int	CCSDS_istreamFileOpen (CCSDS_istream *istream, char const *filename, unsigned int options, unsigned char *buf, unsigned int buf_size)
	Convenience function to construct a CCSDS_istream to read from the specified named file filename.
unsigned int	CCSDS_istreamTell (CCSDS_istream const *istream)
	Returns the current byte offset into the stream.
int	CCSDS_istreamProcess (CCSDS_istream *stream, CCSDS_istreamCsb *csb, CCSDS_istreamResolver resolve_rtn, void *resolve_ctx)
	Processes a stream of CCSDS packets. The packets may be from multiple APIDs.
int	CCSDS_istreamClose (CCSDS_istream *istream)
	Closes the input stream associated with istream.
int	CCSDS_istreamDestroy (CCSDS_istream *istream)
	Destroys (i.e. returns the resources) associated with the stream.
void	CCSDS_istreamHdrPrint (CCSDS_telemetry const *packet)
	Prints a one-line summary of the CCSDS_istream header.

---

Detailed Description

Input CCSDS packets.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: CCSDS_istream.c,v 1.8 2011/03/26 21:06:58 russell Exp $

---

Function Documentation

int CCSDS_istreamClose

(

CCSDS_istream *

istream

)

Closes the input stream associated with istream.

Returns:

Status

Parameters:

istream

The stream to close

Note:

This does not free/destroy the istream control structure, it merely closes the physical stream associated with it.

References _CCSDS_istreamInput::close, _CCSDS_istream::input, and _CCSDS_istreamInput::prm.

int CCSDS_istreamConnect	(	CCSDS_istream *	istream,
		void *	prm,
		CCSDS_istreamReader	read,
		CCSDS_istreamCloser	close,
		CCSDS_istreamTeller	tell
	)

Connects a read mechanism with the specified stream.

Return values:

0,Always

Parameters:

	istream	The target CCSDS_istream
	prm	Arbitrary user context parameter passed to the read routine
	read	The routine used to read from the underlying physical data stream
	close	The routine used to close the underlying physical stream
	tell	The routine used to get the current position in the stream.

References _CCSDS_istreamInput::close, _CCSDS_istream::input, _CCSDS_istreamInput::read, and _CCSDS_istreamInput::tell.

int CCSDS_istreamConstruct

(

CCSDS_istream *

istream

)

Constructs (initializes) a previously uninitialized CCSDS_istream control structure.

Return values:

	==0,Successful
	!=0,Failure	(currently the routine always succeeds

Parameters:

istream

The CCSDS_istream structure to construct (initialize)

References construct().

int CCSDS_istreamDatAdvance	(	CCSDS_istream *	istream,
		CCSDS_telemetry const *	packet,
		CCSDS_apidDsc *	dsc
	)

Advances past the current CCSDS data payload with reading the data into the buffer. All integrity checks are preformed. This in contrast with calling CCSDS_istreamDatRead with a NULL descriptor.

Returns:

If descriptor is non-NULL, then the State Information Vector. This is a heavily bit-encoded 32-bit word, see CCSDS_ISTREAM_SIV_M, for example for the meanings of these bits. Consult the dsc->status word for more information

If descriptor is NULL, then the code from the reader (most likely a UNIX errno).

Parameters:

	istream	The target CCSDS_istream structure
	packet	The packet header associated with the data about to be read
	dsc	The target APIDs descriptor, this may be NULL, in which case the data bytes are just skipped, with no checking, In this case the routine behaves identically to CCSDS_istreamDatRead with the same arguments.

References CCSDS__telemetrySequenceFlags(), CCSDS__telemetrySequenceNumber(), CCSDS__telemetrySsrLength(), CCSDS_istreamSivFlagsUpdate(), CCSDS_istreamSivIoUpdate(), CCSDS_istreamSivIsError(), check_sequencing(), form_transition(), _CCSDS_istream::input, _CCSDS_istreamInput::prm, _CCSDS_istreamInput::read, _CCSDS_apidDsc::seq, _CCSDS_apidDsc::siv, and _CCSDS_apidDsc::status.

Referenced by CCSDS_istreamPktResynch(), and CCSDS_istreamProcess().

int CCSDS_istreamDatRead	(	CCSDS_istream *	istream,
		CCSDS_telemetry const *	packet,
		CCSDS_apidDsc *	dsc
	)

Reads the current CCSDS data payload into the buffer specified by dsc.

Returns:

If descriptor is non-NULL, then the State Information Vector. This is a heavily bit-encoded 32-bit word, see CCSDS_ISTREAM_SIV_M, for example for the meanings of these bits. Consult the dsc->status word for more information

If descriptor is NULL, then the code from the reader (most likely a UNIX errno).

Parameters:

	istream	The target CCSDS_istream structure
	packet	The packet header associated with the data about to be read
	dsc	The target APIDs descriptor

If there was insufficient space in the descriptor's read buffer to perform the read, no bytes are read, but rather, the return value is set to indicate insufficient space and the descriptor's status word (dsc->status) is set to the number of bytes needed. The user may increase the descriptors read buffer side and then recall this routine.

References _CCSDS_apidDsc::bridge, _CCSDS_apidDsc::buf, CCSDS__telemetrySequenceFlags(), CCSDS__telemetrySequenceNumber(), CCSDS__telemetrySsrLength(), CCSDS__telemetrySsrPad(), CCSDS_APIDDSC_BRIDGE_K_PAD, CCSDS_APIDDSC_BRIDGE_K_PAYLOAD, CCSDS_ISTREAM_PKT_STATE_K_FIRST, CCSDS_ISTREAM_SIV_M_ERR_OVRRUN, CCSDS_ISTREAM_SIV_M_ERR_SUMMARY, CCSDS_istreamSivFlagsUpdate(), CCSDS_istreamSivIoUpdate(), CCSDS_istreamSivIsError(), check_sequencing(), _CCSDS_apidDsc::cur, form_transition(), _CCSDS_istream::input, _CCSDS_apidDsc::max, _CCSDS_telemetry::payload, _CCSDS_istreamInput::prm, _CCSDS_istreamInput::read, _CCSDS_apidDsc::seq, _CCSDS_apidDsc::siv, and _CCSDS_apidDsc::status.

Referenced by CCSDS_istreamPktResynch(), and CCSDS_istreamProcess().

int CCSDS_istreamDestroy

(

CCSDS_istream *

istream

)

Destroys (i.e. returns the resources) associated with the stream.

Returns:

Status

Parameters:

istream

The stream to destroy.

References _CCSDS_istream::free.

int CCSDS_istreamFileOpen	(	CCSDS_istream *	istream,
		char const *	filename,
		unsigned int	options,
		unsigned char *	buf,
		unsigned int	buf_size
	)

Convenience function to construct a CCSDS_istream to read from the specified named file filename.

Returns:

0, If successful

-1, If could not allocate a new stream (i.e. out of memory)

-2, If the file does not exist

Parameters:

	istream	The target CCSDS_istream
	filename	The name of the file to open
	options	Bit list of options, currently unused, specify as 0
	buf	Optional parameter specifying the FILE's input read buffer
	buf_size	Optional parameter specifying the size of buf

References CCSDS_istreamNew(), _CCSDS_istreamInput::close, file_read(), _CCSDS_istream::input, _CCSDS_istreamInput::prm, _CCSDS_istreamInput::read, and _CCSDS_istreamInput::tell.

void CCSDS_istreamHdrPrint

(

CCSDS_telemetry const *

packet

)

Prints a one-line summary of the CCSDS_istream header.

Parameters:

packet

The packet header to print

References CCSDS__telemetrySequenceFlags(), CCSDS_TELEMETRY_PRINT_OPTS_M_ALL, CCSDS_TELEMETRY_PRINT_OPTS_M_HEADER, and CCSDS_telemetryPrint().

int CCSDS_istreamHdrRead	(	CCSDS_istream *	istream,
		CCSDS_telemetry *	packet
	)

Reads the CCSDS header.

Return values:

	0,Success
	-1,End	Of Stream
	Anything	else, error number (errno)

Parameters:

	istream	The target CCSDS_istream
	packet	The destination CCSDS telemetry packet header

After reading the header and checking to see if the read is successful, the user should call CCSDS_telemetryVerify to verify that the header is okay. This provides some protection, although not a lot because the internal consistency checks to do the verification of telemetry are not that strong, something like 4 bits. See CCSDS__telemetryVerify for an explanation.

Note:

The odd 16-bit word after the normal 7 x 16bit word CCSDS header is also read by this routine. Technically this is not correct. It is not until the apid is read does one really know if this word belongs with the header or the data. However, the only time one can get into trouble is if this word does not exist at all. In this case, two bad things can happen 1. The word does not even exist in the input stream. This means one has over-read by 2 bytes, which will falsely cause an EOF. This is not too bad because it can be checked if need be. 2. The word belongs to the next CCSDS packet. In this case, the order needs to be 'put' back into the IO stream so the next packet can find it. This can be done, but it is ugly. (More reasonable is that when CCSDS_istreamDatRead or CCSDS_istreamHdrRead attempts to move past the data, it will discover that the remaining data is -2. It could then 'stash' these 2 bytes away so that CCSDS_istreamHdr could check on the next read to see if the exist, and if so, 'read' them first, then the rest of the header.

However the tactic taken here is to bury one's head in the sand and ignore the issue. The LAT currently has no packets that are dataless. If the need arises, the out list above in (2) will be taken.

References CCSDS__telemetrySsrSwapb(), _CCSDS_istream::input, _CCSDS_istreamInput::prm, and _CCSDS_istreamInput::read.

Referenced by CCSDS_istreamProcess().

CCSDS_istream* CCSDS_istreamNew

(

void

)

Convenience function to allocate and initialize a CCSDS_istream control structure.

Returns:

Pointer to the allocated CCSDS_istream control structure

References construct().

Referenced by CCSDS_istreamFileOpen().

int CCSDS_istreamPktCheck	(	unsigned int	opts,
		CCSDS_istream *	istream,
		CCSDS_telemetry const *	pkt,
		CCSDS_apidDsc *	dsc
	)

Precanned CCSDS_istreamProcess callback routine to check the integrity of a CCSDS packet.

Return values:

	==	0, meaning to continue
	!=	0, stop (it actually returns the erroring siv, but the public interface to the checker routine is simply 0 for success and non-zero for error.

Parameters:

opts

A bit mask of options,

See also:

CCSDS_ISTREAM_PKT_CHECK_OPTS_M

Parameters:

	istream	The CCSDS_istream handle
	pkt	The CCSDS packet to check
	dsc	The descriptor for this APID stream.

The user of the CCSDS_istreamProcess framework may use this routine as his APID specific packet checker or as a template to writing his own. This routine, with the opts argument set to a value of 0, will be used if the user does not provide one.

References CCSDS__telemetryApid(), CCSDS__telemetrySequenceFlags(), CCSDS__telemetrySequenceNumber(), CCSDS_ISTREAM_PKT_CHECK_OPTS_M_NOPRINT_SIV_ERR, CCSDS_ISTREAM_PKT_CHECK_OPTS_M_NOPRINT_SYNCH_ERR, CCSDS_ISTREAM_PKT_CHECK_OPTS_M_NORESYNCH, CCSDS_ISTREAM_PKT_CHECK_OPTS_M_PRINT_HDR, CCSDS_ISTREAM_SIV_M_CUR_FIRST, CCSDS_ISTREAM_SIV_M_PRV_LAST, CCSDS_istreamPktResynch(), CCSDS_istreamSivCurFlags(), CCSDS_istreamSivIsError(), CCSDS_istreamSivIsResynchable(), CCSDS_TELEMETRY_PRINT_OPTS_M_ALL, CCSDS_TELEMETRY_PRINT_OPTS_M_HEADER, CCSDS_telemetryPrint(), report_siv_error(), _CCSDS_apidDsc::seq, and _CCSDS_apidDsc::siv.

Referenced by CCSDS_istreamProcess().

int CCSDS_istreamPktResynch	(	CCSDS_istream *	istream,
		CCSDS_telemetry const *	packet,
		CCSDS_apidDsc *	dsc
	)

Routine to recover from an APID sequence number or sequence state (first, middle, last) packet error. It can be used part of the CCSDS_istreamProcess packer checker routine.

Returns:

The updated siv.

Parameters:

	istream	The CCSDS istream handle
	packet	The telemety packet. Only the header need be present
	dsc	The APID stream descriptor

References CCSDS__telemetrySequenceFlags(), CCSDS_apidDscReset(), CCSDS_istreamDatAdvance(), CCSDS_istreamDatRead(), CCSDS_istreamSivIoUpdate(), CCSDS_istreamSivIsResynchable(), CCSDS_sequenceFlagsIsFirst(), _CCSDS_apidDsc::siv, and _CCSDS_apidDsc::status.

Referenced by CCSDS_istreamPktCheck().

int CCSDS_istreamProcess	(	CCSDS_istream *	stream,
		CCSDS_istreamCsb *	csb,
		CCSDS_istreamResolver	resolve_rtn,
		void *	resolve_ctx
	)

Processes a stream of CCSDS packets. The packets may be from multiple APIDs.

Returns:

See the enumeration CCSDS_ISTREAM_STATUS_K

Parameters:

	stream	The stream of CCSDS packets
	csb	The completion status block. This contains details about the processing. In particular, it contains the returned status value of the routine that stopped the processing and, if applicable, the apid descriptor that was active when the processing was stopped.
	resolve_rtn	Routine to resolve the APID to an APID descriptor. If NULL, only packet level processing can be done
	resolve_ctx	Context parameter for the resolve_rtn

This routine can be used for a variety of purposes through the use of the various callback routines.

Use Case 1 - Basic Packet Integrity check

Have the resolve routine return a descriptor for every that has no checker or processing routine. Set the return value to CCSDS_ISTREAM_RESOLVE_STATUS_K_IGNORE. Since no data is being read, the descriptor does not need to provide a buffer.

Use Case 2 - More Involve Packet Integrity

Have the resolve routine return a descriptor for every that has a checker but no processing routine. Set the return value to CCSDS_ISTREAM_RESOLVE_STATUS_K_FOUND.

Use Case 3 - Packet Assembler

Have the resolve routine return a descriptor for every that has no checker but does have processing routine whose only function is to return a non-zero value indicating to stop processing. Control will be returned to the caller with a status of CCSDS_ISTREAM_STATUS_K_PROCESS_STOP. The descriptor of the assembled packet will be in the CCSDSS_istreamCsb (completion status block).

Use Case 4 - Packet Processor

References CCSDS__telemetryVerify(), CCSDS_APIDDSC_POPTS_M_SWAP, CCSDS_apidDscPktBeg(), CCSDS_apidDscPktLen(), CCSDS_apidDscSwap32(), CCSDS_ISTREAM_RESOLVER_STATUS_K_IGNORE, CCSDS_ISTREAM_RESOLVER_STATUS_K_NOTFOUND, CCSDS_ISTREAM_STATUS_K_CHECKER_STOP, CCSDS_ISTREAM_STATUS_K_EOS, CCSDS_ISTREAM_STATUS_K_IO_HEADER_ERROR, CCSDS_ISTREAM_STATUS_K_IO_SKIP_ERROR, CCSDS_ISTREAM_STATUS_K_PROCESSOR_STOP, CCSDS_ISTREAM_STATUS_K_RESOLVER_STOP, CCSDS_ISTREAM_STATUS_K_VERIFY_ERROR, CCSDS_istreamDatAdvance(), CCSDS_istreamDatRead(), CCSDS_istreamHdrRead(), CCSDS_istreamPktCheck(), CCSDS_istreamSivIsLast(), _CCSDS_apidHandlers::checker_ctx, _CCSDS_apidHandlers::checker_rtn, _CCSDS_istreamCsb::dsc, _CCSDS_apidDsc::handler, _CCSDS_istreamCsb::pkt, _CCSDS_istream::pkt, _CCSDS_apidDsc::popts, _CCSDS_apidHandlers::processor_ctx, _CCSDS_apidHandlers::processor_rtn, _CCSDS_apidDsc::siv, and _CCSDS_istreamCsb::status.

int CCSDS_istreamSizeof

(

void

)

Returns the size, in bytes, of a CCSDS_istream structure.

Returns:

The size, in bytes, of a CCSDS_istream structure

unsigned int CCSDS_istreamTell

(

CCSDS_istream const *

istream

)

Returns the current byte offset into the stream.

Returns:

The current byte offset into the stream, i.e. the read pointer

Parameters:

istream

The target CCSDS_istream

References _CCSDS_istream::input, _CCSDS_istreamInput::prm, and _CCSDS_istreamInput::tell.

static __inline unsigned int check_sequencing	(	unsigned int	siv,
		unsigned short int	flags,
		unsigned short int	prv_seq,
		unsigned short int	sequence
	)			[static]

Checks that both the packet transition from the previous state to the current state is allowed and that the sequence number advances correctly. Note that this routine only checks the integrity, it does not update any state information.

Returns:

The updated SIV

Parameters:

	siv	The current SIV
	flags	The new sequence flags
	prv_seq	The previous sequence number
	sequence	The new sequence number

References CCSDS_APIDDSC_K_SEQ_RESET, CCSDS_ISTREAM_SIV_M_ERR_SEQ, CCSDS_ISTREAM_SIV_M_ERR_SEQNUM, CCSDS_ISTREAM_SIV_M_ERR_SUMMARY, CCSDS_M_SEQ, and check_transition().

Referenced by CCSDS_istreamDatAdvance(), and CCSDS_istreamDatRead().

static int __inline check_transition

(

unsigned int

state

)

[static]

Checks that the transition from the previous state to the current state is allowed.

Return values:

	0,Transition	is allowed
	!=0,Transition	is not allowed

Parameters:

state

The 4-bit state transition word

This routine checks that the transition from the transition of the previous packet to the state of the current packet is allowed.

Referenced by check_sequencing().

static CCSDS_istream * construct	(	CCSDS_istream *	istream,
		int	free
	)			[static]

Construct for a newly minted CCSDS_istream structure.

Returns:

istream

Parameters:

	istream	The structure to initialize
	free	If non-zero, this structure should be freed by CCSDS_istreamFree

References _CCSDS_istreamInput::close, _CCSDS_istream::free, _CCSDS_istream::input, _CCSDS_istreamInput::prm, and _CCSDS_istreamInput::read.

Referenced by CCSDS_istreamConstruct(), and CCSDS_istreamNew().

static int file_read	(	FILE *	file,
		unsigned char *	buf,
		int	nbytes,
		int	sbytes
	)			[static]

Simple routine to do a file read using fread.

Return values:

	0,Success
	-1,End	Of Stream
	Anything	else, error number (errno)

Parameters:

	file	The file stream to read from
	buf	The buffer, guaranteed to be nbytes in length
	nbytes	The number of bytes to read. If non-zero, these bytes are read before skipping over sbytes and, typically are the data bytes of the packet.
	sbytes	The number of bytes that should be skipped. These bytes are not read, but the stream position counter is advance. Typically this is the number of pad bytes, but it can also be used to skip over the entire chunk of data.

Referenced by CCSDS_istreamFileOpen().

static int __inline form_transition	(	unsigned int	siv,
		unsigned short int	flags
	)			[static]

Forms the new state transition word. This consists of 2 bits defining the previous packet state (ONLY, FIRST, MIDDLE, LAST) and 2 bits defining the current packet state.

Parameters:

	siv	The state information vector containing the state of the previous packet
	flags	The flags of current CCSDS packet (right justified)

The state of packet is defined as ONLY packet or the FIRST, MIDDLE of LAST of a sequence.

References CCSDS_ISTREAM_SIV_M_CUR, and CCSDS_ISTREAM_SIV_V_CUR.

Referenced by CCSDS_istreamDatAdvance(), and CCSDS_istreamDatRead().

static void report_siv_error	(	int	siv,
		int	apid,
		int	seq
	)			[static]

Reports the reasons for CCSDS siv errors.

Parameters:

	siv	The CCSDS istream state information vector
	apid	The APID of the erring packet
	seq	The sequence number of the erring packet

References CCSDS_ISTREAM_SIV_M_ERR.

Referenced by CCSDS_istreamPktCheck().