source/dsfm/inc/dsfm.h

Go to the documentation of this file.

/*******************************************************************************
 * Copyright © 2014 The DTVKit Open Software Foundation Ltd (www.dtvkit.org)
 * Copyright © 2004 Ocean Blue Software Ltd
 *
 * This file is part of a DTVKit Software Component
 * You are permitted to copy, modify or distribute this file subject to the terms
 * of the DTVKit 1.0 Licence which can be found in licence.txt or at www.dtvkit.org
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
 * EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
 *
 * If you or your organisation is not a member of DTVKit then you have access
 * to this source code outside of the terms of the licence agreement
 * and you are expected to delete this and any associated files immediately.
 * Further information on DTVKit, membership and terms can be found at www.dtvkit.org
 *******************************************************************************/
#ifndef _DSFM_H_
#define _DSFM_H_

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

#define SECTION_HEADER_LENGTH 8

typedef enum {
   SFM_ERROR,
   SFM_IGNORE,
   SFM_UPDATE_CACHE,
   SFM_UPDATE_LOW,
   SFM_UPDATE_HIGH
} E_SFM_STATUS;

typedef struct s_DmxPidFilter*   H_DmxPidFilter;

/*------------------- Functions supplied to SFM at setup ---------------------*/

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

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

/*---------------- Setup structure for SFM initialisation -------------------*/

typedef struct
{
   /* ---------- Manditory functions ----------- */

   F_MemAlloc           memAlloc;
   F_MemFree            memFree;

   F_Locking            mutexLock;
   F_Locking            mutexUnlock;

   /* Hardware filter callback function that will handle section and lead to
    * calling SFM_RequireSection() followed by SFM_ProcessSection()
    */
   F_FILTER_CALLBACK    hwFilterCallback;

   /* Callback function to inform client that filters require updating
    */
   F_UpdateFilter       updateFilter;

   /* ---------- Optional functions ----------- */

   /* cacheMatch function provided so that processing of section data matched
    * in cache can happen after DSM-CC has finished processing request for
    * relevant section filter.
    * If 'cacheMatch' is NULL, then SFM_DsmccFilterAdd will directly call
    * SFM_ProcessSection.
    */
   F_CacheMatch         cacheMatch;

   /* -------- Optional debug functions --------- */

   /* errPrintf and dbgPrintf functions are only used in a debug build
    * When not supplied, these must be set to NULL
    */
   F_Printf             errPrintf;
   F_Printf             dbgPrintf;

   /* ------------- Mutex parameters ------------ */

   /* sfmMutex is manditory, used in mutexLock / mutexUnlock functions
    * and must be created and valid before supplying to SFM_CreateInstance
    */
   void*                sfmMutex;

   /* cacheMutex and bufferMutex are only required.if caching
    * - see sectionBuffCacheSize
    * It if used in mutexLock / mutexUnlock functions and must be created
    * before supplying to SFM_CreateInstance
    */
   void*                cacheMutex;
   void*                bufferMutex;

   /* -------- Configuration parameters --------- */

   /* Set maximum number of PID filters available to be used symultaneously
    * Minimum value: 4
    */
   U8BIT                maxPidFilters;

   /* Set maximum number of section filters per PID filter used symultaneously.
    * Low values will increase requirement for SFM to do it's own
    * software section filtering.
    * Minimum value: 1
    */
   U8BIT                maxSecFiltersPerPid;

   /* Size of section buffer manager cache in 64K byte blocks. This memory is
    * used to store section data not immediately required by DSM-CC instance.
    * This facilitates faster DSM-CC file loading - particularly when the number
    * of section filters is limited. See maxSecFiltersPerPid (and maxPidFilters)
    * Minimum value: 0
    * Suggested value: 16
    */
   U8BIT                sectionBuffCacheSize;

   /*
    * Specifies the maximum number of section filters that are available
    * to the DSM-CC instance for simultaneously acquiring DSM-CC private sections.
    * This should be set with the same value as that given to the DSM-CC instance
    * creation - see 'maxAvailableSectionFilters' in DSM-CC setup.
    */
   U16BIT               maxAvailableSectionFilters;

   /* dbgState controls type of debug output for dbgPrintf
    * For valid debug filter states see above
    */
   U32BIT               dbgState;

} S_SfmSetup;


/*---------------------- Functions that configure SFM ------------------------*/

H_SfmInstance SFM_CreateInstance( S_SfmSetup *pSetup );

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

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

void SFM_SetDebugState( H_SfmInstance sfm, U32BIT dbgState );

void SFM_SetDsmInstance( H_SfmInstance sfm, clDsmInstHandle_t dsmcc );

void SFM_SetDemuxHandle( H_SfmInstance sfm, DMXREF demux );



/*----------------- Functions that process section data  ---------------------*/

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

U8BIT* SFM_CacheBuffer( H_SfmInstance sfm, void* hBuffer );

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

void SFM_FilterUpdate( H_SfmInstance sfm, H_DmxPidFilter hPF );

/*-------------------- Functions to manage SFM caching -----------------------*/

BOOLEAN SFM_CacheEnableSSF( H_SfmInstance sfm );

void SFM_CacheDisableSSF( H_SfmInstance sfm );

void SFM_CacheClear( H_SfmInstance sfm );



/*----------------- Functions provided to DSM-CC component -------------------*/

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

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


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

#endif /*_DSFM_H_*/