Dsmcc's Section Filter Manager API. More...

#include "cldsmtypes.h"
#include "dmxtypes.h"
#include "stdfuncs.h"
#include "stb_filter.h"
#include "dsm_debug.h"

Data Structures
struct	S_SfmSetup
Defines
#define	SECTION_HEADER_LENGTH 8
Typedefs
typedef struct s_DmxPidFilter *	H_DmxPidFilter
typedef void(*	F_UpdateFilter )(H_SfmInstance sfm, H_DmxPidFilter hPF)
	Report to SFM client that there is a filter update to be processed. The client must place the request on a queue that will subsequently cause SFM_FilterUpdate to be called.
typedef void(*	F_CacheMatch )(H_SfmInstance sfm, U8BIT pSection, void hBuffer, E_SFM_STATUS status)
	Report to SFM client that there is an update to be processed. This is called in the normal DSM-CC thread environment, and is due to SFM finding section data in cache. The client may place the request on a queue that subsequently causes SFM_ProcessSection to be called.
Enumerations
enum	E_SFM_STATUS { SFM_ERROR, SFM_IGNORE, SFM_UPDATE_CACHE, SFM_UPDATE_LOW, SFM_UPDATE_HIGH }
Functions
H_SfmInstance	SFM_CreateInstance (S_SfmSetup *pSetup)
	Create Section Filter Manager instance, using setup structure.
void	SFM_DestroyInstance (H_SfmInstance sfm, void pSfmMtx, void pCchMtx, void **pBufMtx)
	Destroy Section Filter Manager instance, and return mutexes so that they may be destroyed by client.
void	SFM_SetDebugConfig (H_SfmInstance sfm, F_Printf errPrintf, F_Printf dbgPrintf, U32BIT dbgState)
	This allows controlling software to reconfigure SFM debug output.
void	SFM_SetDebugState (H_SfmInstance sfm, U32BIT dbgState)
	This allows controlling software to reconfigure SFM debug output.
void	SFM_SetDsmInstance (H_SfmInstance sfm, clDsmInstHandle_t dsmcc)
	Set instance handle for DSM-CC that SFM is supporting.
void	SFM_SetDemuxHandle (H_SfmInstance sfm, DMXREF demux)
	Set handle to be passed to F_DvpFilterSetup and F_DvpFilterRemove.
E_SFM_STATUS	SFM_RequireSection (H_SfmInstance sfm, PIDFILT pfid, U8BIT pHeader, void *phBuffer)
	This function performs minimal checking of section header data to find out whether SFM requires this section. Number of header bytes required is SECTION_HEADER_LENGTH. It assumes CRC has been checked and is passing valid DSM-CC sections So the first byte of data must be table id 0x3B, 0x3C or 0x3D. Note for multi-tasking: this function uses mutex locking to protect shared data with SFM_DsmccFilterAlloc and SFM_DsmccFilterDelete. It does NOT call any DSM-CC core functions.
U8BIT *	SFM_CacheBuffer (H_SfmInstance sfm, void *hBuffer)
	Get section data buffer pointer in SFM's cache for the handle. This should only be called after SFM_RequireSection returned with SFM_UPDATE_CACHE. This may be called from 'interrupt' environment. The returned pointer may be used by client to copy section data into SFM's cache buffer.
void	SFM_ProcessSection (H_SfmInstance sfm, U8BIT pSection, void hBuffer)
	Process required section buffer. This should only be called after SFM_RequireSection has returned SFM_UPDATE_HIGH or SFM_UPDATE_LOW. This function must be called in the normal DSM-CC thread environment, because it calls DSM-CC core functions.
void	SFM_FilterUpdate (H_SfmInstance sfm, H_DmxPidFilter hPF)
	Update SFM PID filter to configure HW for latest requirements.
BOOLEAN	SFM_CacheEnableSSF (H_SfmInstance sfm)
	Enables Full Sotfware Section Filtering using SFM cache. This will only be successfull if sufficient resources are available.
void	SFM_CacheDisableSSF (H_SfmInstance sfm)
	Disables Sotfware Section Filtering.
void	SFM_CacheClear (H_SfmInstance sfm)
	Clear all SFM cached section data. Not required to be called, if setup had sectionBuffCacheSize set to ZERO. Otherwise, this MUST be called on a transport stream change and optionally called at other times - e.g on a service change.
void *	SFM_DsmccFilterAdd (H_SfmInstance sfm, pclDsmSFilter_t pFilter, clDsmSFRef_t dsmSfRef)
	Add DSM-CC section filter. Called by DSM-CC component, and given in clDsmSysCreate setup. Note for multi-tasking: this function uses mutex locking to protect shared data with SFM_RequireSection.
void	SFM_DsmccFilterDelete (H_SfmInstance sfm, void *filterHandle, clDsmSFRef_t dsmSfRef)
	Delete DSM-CC section filter. Called by DSM-CC component, and given in clDsmSysCreate setup. Note for multi-tasking: this function uses mutex locking to protect shared data with SFM_RequireSection.
void	SFM_DsmccFilterPriorityChange (H_SfmInstance sfm, void *filterHandle, clDsmSFRef_t dsmSfRef, clDsmSFPriority_t priority)
	Change DSM-CC section filter priority Called by DSM-CC component, and given in clDsmSysCreate setup. Note for multi-tasking: this function uses mutex locking to protect shared data with SFM_RequireSection.

Detailed Description

Dsmcc's Section Filter Manager API.

Date:: 16 October 2013

Author:: Adam Sturtridge

Typedef Documentation

typedef void(* F_CacheMatch)(H_SfmInstance sfm, U8BIT *pSection, void *hBuffer, E_SFM_STATUS status)

Report to SFM client that there is an update to be processed. This is called in the normal DSM-CC thread environment, and is due to SFM finding section data in cache. The client may place the request on a queue that subsequently causes SFM_ProcessSection to be called.

Parameters:

H_SfmInstance	sfm SFM instance handle.
U8BIT*	pSection Pointer to section data buffer
void*	hBuffer Section buffer handle
E_SFM_STATUS	status Status of update, either: SFM_UPDATE_LOW or SFM_UPDATE_HIGH

Returns:: void

typedef void(* F_UpdateFilter)(H_SfmInstance sfm, H_DmxPidFilter hPF)

Report to SFM client that there is a filter update to be processed. The client must place the request on a queue that will subsequently cause SFM_FilterUpdate to be called.

Parameters:

H_SfmInstance	sfm SFM instance handle.
H_DmxPidFilter	hPF Handle to SFM pid filter

Returns:: void

Function Documentation

U8BIT* SFM_CacheBuffer	(	H_SfmInstance	sfm,
		void *	hBuffer
	)

Get section data buffer pointer in SFM's cache for the handle. This should only be called after SFM_RequireSection returned with SFM_UPDATE_CACHE. This may be called from 'interrupt' environment. The returned pointer may be used by client to copy section data into SFM's cache buffer.

Parameters:

H_SfmInstance	sfm SFM instance handle.
void*	hBuffer Section buffer handle returned by SFM_RequireSection

Returns:: U8BIT* Pointer to buffer to store section data

void SFM_CacheClear ( H_SfmInstance sfm )

Clear all SFM cached section data. Not required to be called, if setup had sectionBuffCacheSize set to ZERO. Otherwise, this MUST be called on a transport stream change and optionally called at other times - e.g on a service change.

Parameters:

H_SfmInstance sfm SFM instance handle.

Returns:: void.

Clear all SFM cached section data. Not required to be called, if setup had sectionBuffCacheSize set to ZERO. Otherwise, this MUST be called on a transport stream change and optionally called at other times - e.g on a service change.

Parameters:

H_SfmInstance sfm SFM instance handle.

Returns:: void.

void SFM_CacheDisableSSF ( H_SfmInstance sfm )

Disables Sotfware Section Filtering.

Parameters:

H_SfmInstance sfm SFM instance handle.

Returns:: void

BOOLEAN SFM_CacheEnableSSF ( H_SfmInstance sfm )

Enables Full Sotfware Section Filtering using SFM cache. This will only be successfull if sufficient resources are available.

Parameters:

H_SfmInstance sfm SFM instance handle.

Returns:: BOOLEAN TRUE on success

H_SfmInstance SFM_CreateInstance ( S_SfmSetup * pSetup )

Create Section Filter Manager instance, using setup structure.

Parameters:

S_SfmSetup setup setup parameters

Returns:: SFM instance. NULL is failure.

void SFM_DestroyInstance	(	H_SfmInstance	sfm,
		void **	pSfmMtx,
		void **	pCchMtx,
		void **	pBufMtx
	)

Destroy Section Filter Manager instance, and return mutexes so that they may be destroyed by client.

Parameters:

H_SfmInstance	sfm SFM instance handle.
void**	pSfmMtx Pointer to sfmMutex provided in setup
void**	pCchMtx Pointer to cacheMutex provided in setup
void**	pBufMtx Pointer to bufferMutex provided in setup

Returns:: void

void* SFM_DsmccFilterAdd	(	H_SfmInstance	sfm,
		pclDsmSFilter_t	pFilter,
		clDsmSFRef_t	dsmSfRef
	)

Add DSM-CC section filter. Called by DSM-CC component, and given in clDsmSysCreate setup. Note for multi-tasking: this function uses mutex locking to protect shared data with SFM_RequireSection.

Parameters:

H_SfmInstance	sfm SFM instance handle.
pclDsmSFilter_t	pFilter Pointer to DSM-CC filter details
clDsmSFRef_t	dsmSfRef DSM-CC SF reference handle

Returns:: void* SFM Filter handle

Add DSM-CC section filter. Called by DSM-CC component, and given in clDsmSysCreate setup. Note for multi-tasking: this function uses mutex locking to protect shared data with SFM_RequireSection.

Parameters:

H_SfmInstance	sfm SFM instance handle.
pclDsmSFilter_t	pFilter Pointer to DSM-CC filter details
clDsmSFRef_t	dsmSfRef DSM-CC SF reference handle

Returns:: void* SFM Filter handle

void SFM_DsmccFilterDelete	(	H_SfmInstance	sfm,
		void *	filterHandle,
		clDsmSFRef_t	dsmSfRef
	)

Delete DSM-CC section filter. Called by DSM-CC component, and given in clDsmSysCreate setup. Note for multi-tasking: this function uses mutex locking to protect shared data with SFM_RequireSection.

Parameters:

H_SfmInstance	sfm SFM instance handle.
void*	filterHandle SFM Filter handle
clDsmSFRef_t	dsmSfRef DSM-CC reference handle

Returns:: void

Parameters:

H_SfmInstance	sfm SFM instance handle.
void*	filterHandle SFM Filter handle
clDsmSFRef_t	dsmSfRef DSM-CC reference handle

Returns:

void SFM_DsmccFilterPriorityChange	(	H_SfmInstance	sfm,
		void *	filterHandle,
		clDsmSFRef_t	dsmSfRef,
		clDsmSFPriority_t	priority
	)

Change DSM-CC section filter priority Called by DSM-CC component, and given in clDsmSysCreate setup. Note for multi-tasking: this function uses mutex locking to protect shared data with SFM_RequireSection.

Parameters:

H_SfmInstance	sfm SFM instance handle.
void*	filterHandle SFM Filter handle
clDsmSFRef_t	dsmSfRef DSM-CC SF reference handle
clDsmSFPriority_t	priority New filter priority

Returns:: void

Change DSM-CC section filter priority Called by DSM-CC component, and given in clDsmSysCreate setup. Note for multi-tasking: this function uses mutex locking to protect shared data with SFM_RequireSection.

Parameters:

H_SfmInstance	sfm SFM instance handle.
void*	filterHandle SFM Filter handle
clDsmSFRef_t	dsmSfRef DSM-CC SF reference handle
clDsmSFPriority_t	priority New filter priority

Returns:: void

void SFM_FilterUpdate	(	H_SfmInstance	sfm,
		H_DmxPidFilter	pPF
	)

Update SFM PID filter to configure HW for latest requirements.

Parameters:

H_SfmInstance	sfm SFM instance handle.
H_DmxPidFilter	hPF Handle to SFM pid filter

Returns:: void.

Parameters:

H_SfmInstance	sfm SFM instance handle.
H_DmxPidFilter	pPF Handle to SFM pid filter

Returns:: void.

void SFM_ProcessSection	(	H_SfmInstance	sfm,
		U8BIT *	pSection,
		void *	hBuffer
	)

Process required section buffer. This should only be called after SFM_RequireSection has returned SFM_UPDATE_HIGH or SFM_UPDATE_LOW. This function must be called in the normal DSM-CC thread environment, because it calls DSM-CC core functions.

Parameters:

H_SfmInstance	sfm SFM instance handle.
U8BIT*	pSection Pointer to whole section data buffer
void*	hBuffer SFM section handle returned by SFM_RequireSection

Returns:: void.

Process required section buffer. This should only be called after SFM_RequireSection has returned SFM_UPDATE_HIGH or SFM_UPDATE_LOW. This function must be called in the normal DSM-CC thread environment, because it calls DSM-CC core functions.

Parameters:

H_SfmInstance	sfm SFM instance handle.
U8BIT*	pSection Pointer to whole section data buffer
void*	hBuffer SFM section handle returned by SFM_RequireSection

Returns:: void.

E_SFM_STATUS SFM_RequireSection	(	H_SfmInstance	sfm,
		PIDFILT	pfid,
		U8BIT *	pHeader,
		void **	phBuffer
	)

This function performs minimal checking of section header data to find out whether SFM requires this section. Number of header bytes required is SECTION_HEADER_LENGTH. It assumes CRC has been checked and is passing valid DSM-CC sections So the first byte of data must be table id 0x3B, 0x3C or 0x3D. Note for multi-tasking: this function uses mutex locking to protect shared data with SFM_DsmccFilterAlloc and SFM_DsmccFilterDelete. It does NOT call any DSM-CC core functions.

Parameters:

H_SfmInstance	sfm SFM instance handle.
PIDFILT	pfid PID filter with incoming section
U8BIT*	pHeader Pointer to section header (min 8 bytes)
void**	phBuffer Pointer to SFM section buffer handle

Returns:: E_SFM_STATUS - status of required update

This function performs minimal checking of section header data to find out whether SFM requires this section. Number of header bytes required is SECTION_HEADER_LENGTH. It assumes CRC has been checked and is passing valid DSM-CC sections So the first byte of data must be table id 0x3B, 0x3C or 0x3D. Note for multi-tasking: this function uses mutex locking to protect shared data with SFM_DsmccFilterAlloc and SFM_DsmccFilterDelete. It does NOT call any DSM-CC core functions.

Parameters:

H_SfmInstance	sfm SFM instance handle.
PIDFILT	pfid PID filter with incoming section
U8BIT*	pHeader Pointer to section header (min 8 bytes)
void**	phBuffer Pointer to SFM section buffer handle

Returns:: E_SFM_STATUS - status of required update

void SFM_SetDebugConfig	(	H_SfmInstance	sfm,
		F_Printf	errPrintf,
		F_Printf	dbgPrintf,
		U32BIT	dbgState
	)

This allows controlling software to reconfigure SFM debug output.

Parameters:

H_SfmInstance	sfm SFM instance handle.
F_SfmPrintf	errPrintf Error print function
F_SfmPrintf	dbgPrintf Debug print function
U32BIT	dbgState State to filter debug printing

Returns:

void SFM_SetDebugState	(	H_SfmInstance	sfm,
		U32BIT	dbgState
	)

This allows controlling software to reconfigure SFM debug output.

Parameters:

H_SfmInstance	sfm SFM instance handle.
U32BIT	dbgState State to filter debug printing

Returns:

void SFM_SetDemuxHandle	(	H_SfmInstance	sfm,
		DMXREF	demux
	)

Set handle to be passed to F_DvpFilterSetup and F_DvpFilterRemove.

Parameters:

H_SfmInstance	sfm SFM instance handle.
DMXREF	demux Demux reference handle

Returns:

Parameters:

H_SfmInstance	sfm SFM instance handle.
DMXREF	demux Demux handle used by platform

Returns:

void SFM_SetDsmInstance	(	H_SfmInstance	sfm,
		clDsmInstHandle_t	dsmcc
	)

Set instance handle for DSM-CC that SFM is supporting.

Parameters:

H_SfmInstance	sfm SFM instance handle.
clDsmInstHandle_t	dsmcc DSM-CC instance being supported

Returns:

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Function Documentation