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

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

Data Structures
struct	S_SfmSetup

Macros
#define	SECTION_HEADER_LENGTH 8

#define	DF_NONE 0x0000

#define	DF_MAIN 0x0001

#define	DF_FILTER 0x0002

#define	DF_CACHE 0x0004

#define	DF_ALL 0x000f

Typedefs
typedef struct s_DmxPidFilter *	H_DmxPidFilter

typedef PIDFILT(*	F_PidFilterAdd )(DMXREF demux, U16BIT pid)
	Allocate, configure a PID. More...

typedef void(*	F_PidFilterDelete )(DMXREF demux, PIDFILT pfid)
	Delet PID filter. More...

typedef SECFILT(*	F_SecFilterAdd )(DMXREF demux, PIDFILT pfid, U8BIT tid, U8BIT tidMask, U16BIT tidExt, U16BIT tidExtMask)
	Allocate a section filter on supplied PID filter The hardware should acquire all sections matching the table Id and table Id extension where related masking indicates. CRC checking should be enabled in platform. More...

typedef void(*	F_SecFilterDelete )(DMXREF demux, SECFILT sfid)
	Delete section filter. More...

typedef void(*	F_PidFilterStart )(DMXREF demux, PIDFILT pfid)
	Start aquiring section data on PID filter according to all allocated section filters for this PID filter. Stop and Start are called when adding or deleting section filters. More...

typedef void(*	F_PidFilterStop )(DMXREF demux, PIDFILT pfid)
	Stop aquiring section data on PID filter. Stop and Start are called when adding or deleting section filters. More...

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. More...

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. More...

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. More...

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. More...

void	SFM_SetDebugConfig (H_SfmInstance sfm, F_Printf errPrintf, F_Printf dbgPrintf, U32BIT dbgState)
	This allows controlling software to reconfigure SFM debug output. More...

void	SFM_SetDebugState (H_SfmInstance sfm, U32BIT dbgState)
	This allows controlling software to reconfigure SFM debug output. More...

void	SFM_SetDsmInstance (H_SfmInstance sfm, clDsmInstHandle_t dsmcc)
	Set instance handle for DSM-CC that SFM is supporting. More...

void	SFM_SetDemuxHandle (H_SfmInstance sfm, DMXREF demux)
	Set handle to be passed to F_DvpFilterSetup and F_DvpFilterRemove. More...

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. More...

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. More...

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. More...

void	SFM_FilterUpdate (H_SfmInstance sfm, H_DmxPidFilter hPF)
	Update SFM PID filter to configure HW for latest requirements. More...

BOOLEAN	SFM_CacheEnableSSF (H_SfmInstance sfm)
	Enables Full Sotfware Section Filtering using SFM cache. This will only be successfull if sufficient resources are available. More...

void	SFM_CacheDisableSSF (H_SfmInstance sfm)
	Disables Sotfware Section Filtering. More...

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. More...

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. More...

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. More...

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. More...

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 PIDFILT(* F_PidFilterAdd)(DMXREF demux, U16BIT pid)

Allocate, configure a PID.

Parameters

DMXREF	demux Demux reference handle
U16BIT	pid Value of PID

Returns: PIDFILT Handle to the allocated PID filter. INVALID_PIDFILT - failure.

typedef void(* F_PidFilterDelete)(DMXREF demux, PIDFILT pfid)

Delet PID filter.

Parameters

DMXREF	demux Demux reference handle
PIDFILT	pfid PID filter handle

Returns: void

typedef void(* F_PidFilterStart)(DMXREF demux, PIDFILT pfid)

Start aquiring section data on PID filter according to all allocated section filters for this PID filter. Stop and Start are called when adding or deleting section filters.

Parameters

DMXREF	demux Demux reference handle
PIDFILT	pfid PID filter handle

Returns: void

typedef void(* F_PidFilterStop)(DMXREF demux, PIDFILT pfid)

Stop aquiring section data on PID filter. Stop and Start are called when adding or deleting section filters.

Parameters

DMXREF	demux Demux reference handle
PIDFILT	pfid PID filter handle

Returns: void

typedef SECFILT(* F_SecFilterAdd)(DMXREF demux, PIDFILT pfid, U8BIT tid, U8BIT tidMask, U16BIT tidExt, U16BIT tidExtMask)

Allocate a section filter on supplied PID filter The hardware should acquire all sections matching the table Id and table Id extension where related masking indicates. CRC checking should be enabled in platform.

Parameters

DMXREF	demux Demux reference handle
PIDFILT	pfid Handle to allocated PID filter
U8BIT	tid Table Id(s) required
U8BIT	tidMask Mask for tid byte
U16BIT	tidExt Table Id Extension(s)
U16BIT	tidExtMask Mask for tidExt bytes

Returns: SECFILT Handle to the allocated section filter. INVALID_SECFILT - failure.

typedef void(* F_SecFilterDelete)(DMXREF demux, SECFILT sfid)

Delete section filter.

Parameters

DMXREF	demux Demux reference handle
SECFILT	sfid Section filter handle

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

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Function Documentation