QMEM.c File Reference

Interpret MEM package SSR telemetry. More...

#include <string.h>
#include <LSF/LSF.h>
#include <LSF/LSF_ids.h>
#include <PBI/Endianness.h>
#include <QMEM/QMEM.h>

Classes
struct	_QMEM_Dump_Ident
	Indentifying information for a memory dump. More...
struct	_QMEM_Dump_Desc
	Description of a memory dump. More...
struct	_QMEM_Context
	Context of a datagram parsing operation. More...
Defines
#define	QMEM_CONTEXT_VALID_KEY   (('Q'<<24)+('C'<<16)+('T'<<8)+'X')
	Value that indicates a parsing context is valid.
#define	QMEM_MAX_DATAGRAM_BYTES   (2048)
	Maximum size, in bytes, of a memory dump datagram.
#define	QMEM_MAX_DUMP_DATA_BYTES   (QMEM_MAX_DATAGRAM_BYTES)
	Maximum amount, in bytes, of dump data within a datagram.
Typedefs
typedef enum _QMEM_Contribution_Id	QMEM_Contribution_Id
	Typedef for _QMEM_Contribution_Id.
typedef enum _QMEM_Parse_State	QMEM_Parse_State
	Typedef for _QMEM_Parse_State.
typedef struct _QMEM_Dump_Ident	QMEM_Dump_Ident
	Typedef for _QMEM_Dump_Ident.
typedef struct _QMEM_Dump_Desc	QMEM_Dump_Desc
	Typedef for _QMEM_Dump_Desc.
Enumerations
enum	_QMEM_Contribution_Id {   QMEM_CTB_ID_DESC = 1,   QMEM_CTB_ID_DATA = 2 }
	Identifiers of the MEM datagram contributions. More...
enum	_QMEM_Parse_State {   QMEM_STATE_UNKNOWN = 0,   QMEM_STATE_START = 1,   QMEM_STATE_DESC = 2,   QMEM_STATE_DATA = 3 }
	Memory dump parser states. More...
Functions
static int	qmem_context_is_valid (const QMEM_Context *context_p)
	Validate a parsing context.
static void	qmem_swap_copy (unsigned char *dst_p, const unsigned char *src_p, unsigned int num_bytes)
	Copy and byte-swap a buffer of data.
static void	qmem_swap_check (unsigned char *dst_p, const unsigned char *src_p, unsigned int num_bytes, int swapped)
	Copy and possibly byte-swap a buffer of data.
unsigned int	QMEM_sizeof_context (void)
	Return the size of a parsing context.
unsigned int	QMEM_sizeof_max_dump_data (void)
	Return the maximum amount of dump data within a datagram.
unsigned int	QMEM_sizeof_max_datagram (void)
	Return the maximum size of a memory dump datagram.
QMEM_Status	QMEM_init_context (QMEM_Context *context_p, unsigned char *data_buf_p, unsigned int data_buf_bytes)
	Initialize a parsing context.
static QMEM_Status	qmem_check_identity (const LSF_identity *act_id_p, unsigned int exp_type_id, unsigned int exp_version, unsigned int exp_dir)
	Validate an 'identity' value from a header.
QMEM_Status	QMEM_start_parsing (QMEM_Context *context_p, const LSF_datagram *dgm_p, unsigned int dgm_bytes, int dgm_swapped)
	Start parsing a datagram.
static QMEM_Status	qmem_parse_desc_ctb (QMEM_Context *context_p, const LSF_contribution *ctb_p, LSF_contribution_hdr *hdr_p, int dgm_swapped)
	Parse a memory dump description contribution.
static QMEM_Status	qmem_parse_data_ctb (QMEM_Context *context_p, const LSF_contribution *ctb_p, LSF_contribution_hdr *hdr_p, int dgm_swapped)
	Parse a memory dump data contribution.
QMEM_Status	QMEM_parse_contribution (QMEM_Context *context_p, const LSF_contribution *ctb_p, unsigned int dgm_bytes, int dgm_swapped)
	Parse a contribution within a datagram.
QMEM_Status	QMEM_parse_datagram (QMEM_Context *context_p, const LSF_datagram *dgm_p, unsigned int dgm_bytes, int dgm_swapped)
	Parse an entire memory dump datagram.
QMEM_Status	QMEM_status (const QMEM_Context *context_p)
	Return the status of the parsing of the current datagram.
QMEM_Lat_Unit	QMEM_lat_unit (const QMEM_Context *context_p)
	Return the LAT unit that sent a memory dump.
unsigned int	QMEM_tran_id (const QMEM_Context *context_p)
	Return the transaction ID value from the telecommand that requested a memory dump.
unsigned int	QMEM_cmd_fcode (const QMEM_Context *context_p)
	Return the function code of the telecommand that requested a memory dump.
unsigned int	QMEM_start_addr (const QMEM_Context *context_p)
	Return the starting address of a memory dump.
unsigned int	QMEM_num_datagrams (const QMEM_Context *context_p)
	Return the number of datagrams parsed for the memory dump.
unsigned int	QMEM_bytes_dumped (const QMEM_Context *context_p)
	Return the number of bytes dumped.
unsigned int	QMEM_bytes_available (const QMEM_Context *context_p)
	Return the number of dumped bytes that were saved.
unsigned char *	QMEM_data_buf (const QMEM_Context *context_p)
	Return a pointer to a buffer containing saved dump data.

---

Detailed Description

Interpret MEM package SSR telemetry.

**  CVS $Id: QMEM.c,v 1.3 2011/03/30 23:56:36 russell Exp $
**  

These functions interpret the memory dump telemetry sent to the SSR.

---

Enumeration Type Documentation

enum _QMEM_Contribution_Id

Identifiers of the MEM datagram contributions.

Enumerator:

QMEM_CTB_ID_DESC	Memory dump description contribution.
QMEM_CTB_ID_DATA	Memory dump data contribution.

enum _QMEM_Parse_State

Memory dump parser states.

Enumerator:

QMEM_STATE_UNKNOWN	Parser state is unknown.
QMEM_STATE_START	Waiting for description contribution.
QMEM_STATE_DESC	Waiting for data contribution.
QMEM_STATE_DATA	Waiting to start next datagram.

---

Function Documentation

unsigned int QMEM_bytes_available

(

const QMEM_Context *

context_p

)

Return the number of dumped bytes that were saved.

Parameters:

context_p

Pointer to a parsing context.

Returns:

Number of bytes saved.

References _QMEM_Context::bytes_available, and qmem_context_is_valid().

unsigned int QMEM_bytes_dumped

(

const QMEM_Context *

context_p

)

Return the number of bytes dumped.

Parameters:

context_p

Pointer to a parsing context.

Returns:

Number of bytes dumped.

References _QMEM_Context::bytes_dumped, and qmem_context_is_valid().

QMEM_Status qmem_check_identity	(	const LSF_identity *	act_id_p,
		unsigned int	exp_type_id,
		unsigned int	exp_version,
		unsigned int	exp_dir
	)			[static]

Validate an 'identity' value from a header.

Parameters:

	act_id_p	Pointer to the actual identity value.
	exp_type_id	Expected type_id value.
	exp_version	Expected version value.
	exp_dir	Expected dir value.

Returns:

QMEM_Status value.

References QMEM_STATUS_BAD_DIR, QMEM_STATUS_BAD_HDR, QMEM_STATUS_BAD_TYPE, QMEM_STATUS_BAD_VER, and QMEM_STATUS_OK.

Referenced by qmem_parse_data_ctb(), qmem_parse_desc_ctb(), and QMEM_start_parsing().

unsigned int QMEM_cmd_fcode

(

const QMEM_Context *

context_p

)

Return the function code of the telecommand that requested a memory dump.

Parameters:

context_p

Pointer to a parsing context.

Returns:

Function code value.

References _QMEM_Context::desc, _QMEM_Context::desc_valid, _QMEM_Dump_Desc::idents, and qmem_context_is_valid().

int qmem_context_is_valid

(

const QMEM_Context *

context_p

)

[static]

Validate a parsing context.

Parameters:

context_p

Pointer to parsing context.

Return values:

	0	Parsing context is invalid.
	1	Parsing context is valid.

References _QMEM_Context::key, and QMEM_CONTEXT_VALID_KEY.

Referenced by QMEM_bytes_available(), QMEM_bytes_dumped(), QMEM_cmd_fcode(), QMEM_data_buf(), QMEM_lat_unit(), QMEM_num_datagrams(), QMEM_parse_contribution(), qmem_parse_data_ctb(), qmem_parse_desc_ctb(), QMEM_start_addr(), QMEM_start_parsing(), QMEM_status(), and QMEM_tran_id().

unsigned char * QMEM_data_buf

(

const QMEM_Context *

context_p

)

Return a pointer to a buffer containing saved dump data.

Parameters:

context_p

Pointer to a parsing context.

Returns:

Pointer to dump data buffer.

References _QMEM_Context::data_buf_p, and qmem_context_is_valid().

QMEM_Status QMEM_init_context	(	QMEM_Context *	context_p,
		unsigned char *	data_buf_p,
		unsigned int	data_buf_bytes
	)

Initialize a parsing context.

Parameters:

	context_p	Pointer to the parsing context to initialize.
	data_buf_p	Pointer to a buffer to save dumped data.
	data_buf_bytes	Size of the data_buf_p buffer.

Returns:

QMEM_Status value.

References _QMEM_Context::data_buf_bytes, _QMEM_Context::data_buf_p, _QMEM_Context::key, QMEM_CONTEXT_VALID_KEY, QMEM_STATE_START, QMEM_STATUS_OK, _QMEM_Context::state, and _QMEM_Context::status.

QMEM_Lat_Unit QMEM_lat_unit

(

const QMEM_Context *

context_p

)

Return the LAT unit that sent a memory dump.

Parameters:

context_p

Pointer to a parsing context.

Returns:

LAT unit value.

References _QMEM_Context::desc, _QMEM_Context::desc_valid, _QMEM_Dump_Desc::idents, qmem_context_is_valid(), and QMEM_LAT_UNIT_UNKNOWN.

unsigned int QMEM_num_datagrams

(

const QMEM_Context *

context_p

)

Return the number of datagrams parsed for the memory dump.

Parameters:

context_p

Pointer to a parsing context.

Returns:

Number of datagrams parsed.

References _QMEM_Context::num_datagrams, and qmem_context_is_valid().

QMEM_Status QMEM_parse_contribution	(	QMEM_Context *	context_p,
		const LSF_contribution *	ctb_p,
		unsigned int	dgm_bytes,
		int	dgm_swapped
	)

Parse a contribution within a datagram.

Parameters:

	context_p	Pointer to the parsing context for the datagram.
	ctb_p	Pointer to the contribution.
	dgm_bytes	Remaining size, in bytes, of the datagram.
	dgm_swapped	Flag that datagram data is already byte-swapped.

Returns:

QMEM_Status value.

This function can be used as a callback by an external datagram parser when it reaches each contribution header of a memory dump datagram. The opaque context will be updated with the information found in the contribution. When the external parser reaches the end of the datagram, it can use the QMEM_status(), QMEM_lat_unit(), etc. functions to extract information about the datagram.

References qmem_context_is_valid(), QMEM_CTB_ID_DATA, QMEM_CTB_ID_DESC, qmem_parse_data_ctb(), qmem_parse_desc_ctb(), QMEM_STATUS_BAD_TYPE, QMEM_STATUS_NULL_PTR, QMEM_STATUS_OK, QMEM_STATUS_SHORT, QMEM_STATUS_TRUNCATED, qmem_swap_check(), and _QMEM_Context::status.

Referenced by QMEM_parse_datagram().

QMEM_Status qmem_parse_data_ctb	(	QMEM_Context *	context_p,
		const LSF_contribution *	ctb_p,
		LSF_contribution_hdr *	hdr_p,
		int	dgm_swapped
	)			[static]

Parse a memory dump data contribution.

Parameters:

	context_p	Ptr to the parsing context.
	ctb_p	Ptr to the contribution.
	hdr_p	Ptr to the contribution header in proper byte order.
	dgm_swapped	Flag that datagram data is already byte-swapped.

Returns:

QMEM_Status value.

References _QMEM_Context::bytes_available, _QMEM_Context::bytes_dumped, _QMEM_Context::data_buf_bytes, _QMEM_Context::data_buf_p, _QMEM_Context::num_datagrams, qmem_check_identity(), qmem_context_is_valid(), QMEM_CTB_ID_DATA, QMEM_STATE_DATA, QMEM_STATE_DESC, QMEM_STATUS_BAD_CTX, QMEM_STATUS_BAD_HDR, QMEM_STATUS_OK, qmem_swap_copy(), _QMEM_Context::state, and _QMEM_Context::status.

Referenced by QMEM_parse_contribution().

QMEM_Status QMEM_parse_datagram	(	QMEM_Context *	context_p,
		const LSF_datagram *	dgm_p,
		unsigned int	dgm_bytes,
		int	dgm_swapped
	)

Parse an entire memory dump datagram.

Parameters:

	context_p	Pointer to a parsing context for the datagram.
	dgm_p	Pointer to the datagram.
	dgm_bytes	Size, in bytes, of the datagram.
	dgm_swapped	Flag that datagram data is already byte-swapped.

Returns:

QMEM_Status value.

This function uses the QMEM_start_parsing() and QMEM_parse_contribution() functions to walk through and parse an entire memory dump datagram. The QMEM_status(), QMEM_lat_unit(), etc. functions can then be used to extract information about the datagram.

References QMEM_parse_contribution(), QMEM_start_parsing(), QMEM_STATUS_OK, and qmem_swap_check().

QMEM_Status qmem_parse_desc_ctb	(	QMEM_Context *	context_p,
		const LSF_contribution *	ctb_p,
		LSF_contribution_hdr *	hdr_p,
		int	dgm_swapped
	)			[static]

Parse a memory dump description contribution.

Parameters:

	context_p	Pointer to the parsing context.
	ctb_p	Pointer to the contribution.
	hdr_p	Ptr to the contribution header in proper byte order.
	dgm_swapped	Flag that datagram data is already byte-swapped.

Returns:

QMEM_Status value.

References _QMEM_Dump_Desc::address, _QMEM_Context::bytes_dumped, _QMEM_Context::desc, _QMEM_Context::desc_valid, _QMEM_Dump_Desc::idents, qmem_check_identity(), qmem_context_is_valid(), QMEM_CTB_ID_DESC, QMEM_STATE_DESC, QMEM_STATE_START, QMEM_STATUS_BAD_CTB_LEN, QMEM_STATUS_BAD_CTX, QMEM_STATUS_BAD_HDR, QMEM_STATUS_NOT_NEXT, QMEM_STATUS_OK, qmem_swap_check(), _QMEM_Context::state, and _QMEM_Context::status.

Referenced by QMEM_parse_contribution().

unsigned int QMEM_sizeof_context

(

void

)

Return the size of a parsing context.

Returns:

Size, in bytes, of a parsing context.

unsigned int QMEM_sizeof_max_datagram

(

void

)

Return the maximum size of a memory dump datagram.

Returns:

Maximum size, in bytes, of a memory dump datagram.

References QMEM_MAX_DATAGRAM_BYTES.

unsigned int QMEM_sizeof_max_dump_data

(

void

)

Return the maximum amount of dump data within a datagram.

Returns:

Maximum amount, in bytes, of dump data within a datagram.

References QMEM_MAX_DUMP_DATA_BYTES.

unsigned int QMEM_start_addr

(

const QMEM_Context *

context_p

)

Return the starting address of a memory dump.

Parameters:

context_p

Pointer to a parsing context.

Returns:

Starting address value.

References _QMEM_Dump_Desc::address, _QMEM_Context::desc, _QMEM_Context::desc_valid, and qmem_context_is_valid().

QMEM_Status QMEM_start_parsing	(	QMEM_Context *	context_p,
		const LSF_datagram *	dgm_p,
		unsigned int	dgm_bytes,
		int	dgm_swapped
	)

Start parsing a datagram.

Parameters:

	context_p	Pointer to a parsing context for the datagram.
	dgm_p	Pointer to the datagram.
	dgm_bytes	Size, in bytes, of the datagram.
	dgm_swapped	Flag that datagram data is already byte-swapped.

Returns:

QMEM_Status value.

References qmem_check_identity(), qmem_context_is_valid(), QMEM_STATE_START, QMEM_STATUS_NULL_PTR, QMEM_STATUS_OK, QMEM_STATUS_SHORT, QMEM_STATUS_TRUNCATED, qmem_swap_check(), _QMEM_Context::state, and _QMEM_Context::status.

Referenced by QMEM_parse_datagram().

QMEM_Status QMEM_status

(

const QMEM_Context *

context_p

)

Return the status of the parsing of the current datagram.

Parameters:

context_p

Pointer to a parsing context.

Returns:

Current parsing status.

References qmem_context_is_valid(), QMEM_STATE_DATA, QMEM_STATUS_BAD_CTX, QMEM_STATUS_INCOMPLETE, QMEM_STATUS_OK, _QMEM_Context::state, and _QMEM_Context::status.

void qmem_swap_check	(	unsigned char *	dst_p,
		const unsigned char *	src_p,
		unsigned int	num_bytes,
		int	swapped
	)			[static]

Copy and possibly byte-swap a buffer of data.

Parameters:

	dst_p	Pointer to destination buffer.
	src_p	Pointer to source buffer.
	num_bytes	Number of bytes to copy and byte-swap.
	swapped	Flag indicating that data is already swapped.

Returns:

Nothing.

References qmem_swap_copy().

Referenced by QMEM_parse_contribution(), QMEM_parse_datagram(), qmem_parse_desc_ctb(), and QMEM_start_parsing().

void qmem_swap_copy	(	unsigned char *	dst_p,
		const unsigned char *	src_p,
		unsigned int	num_bytes
	)			[static]

Copy and byte-swap a buffer of data.

Parameters:

	dst_p	Pointer to destination buffer.
	src_p	Pointer to source buffer.
	num_bytes	Number of bytes to copy and byte-swap.

Returns:

Nothing.

Referenced by qmem_parse_data_ctb(), and qmem_swap_check().

unsigned int QMEM_tran_id

(

const QMEM_Context *

context_p

)

Return the transaction ID value from the telecommand that requested a memory dump.

Parameters:

context_p

Pointer to a parsing context.

Returns:

Transaction ID value.

References _QMEM_Context::desc, _QMEM_Context::desc_valid, _QMEM_Dump_Desc::idents, and qmem_context_is_valid().