clDsmSystem.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
 * Copyright © 2001 Koninklijke Philips Electronics N.V
 *
 * 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 _CLDSMSYSTEM_H_
#define _CLDSMSYSTEM_H_


/*---includes for this file--------------------------------------------------*/

#include "cldsmcc.h"
#include "clDsmMemMgrAPI.h"
#include "dsmDbg.h"

#ifdef __cplusplus
extern "C" {
#endif


/*---Constant and macro definitions for public use---------------------------*/

/* -- Turn off all static declarations in debug mode to enable
   -- glowcode profiler to detect them */
#if (!defined(NDEBUG) && defined(DSM_PROFILING_BUILD))
#define static
#endif

/* -- Context defines */
#ifndef DSM_NO_MEM_CONTEXT
#define DSM_CONTEXT_DEFN    pclDsmInstData_t idp
#define DSM_CONTEXT         idp
#define MEM_CONTEXT         idp->memContext
#endif


/* -- General purpose defines */

#define BIT0_MSK    0x01
#define BIT1_MSK    0x02
#define BIT2_MSK    0x04
#define BIT3_MSK    0x08
#define BIT4_MSK    0x10
#define BIT5_MSK    0x20
#define BIT6_MSK    0x40
#define BIT7_MSK    0x80

#define BIT8_MSK    0x0100
#define BIT9_MSK    0x0200
#define BIT10_MSK   0x0400
#define BIT11_MSK   0x0800
#define BIT12_MSK   0x1000
#define BIT13_MSK   0x2000
#define BIT14_MSK   0x4000
#define BIT15_MSK   0x8000

#define LSB1_MSK    0x01
#define LSB2_MSK    0x03
#define LSB3_MSK    0x07
#define LSB4_MSK    0x0F
#define LSB5_MSK    0x1F
#define LSB6_MSK    0x3F
#define LSB7_MSK    0x7F
#define LSB8_MSK    0xFF

#define LSB9_MSK    0x01FF
#define LSB10_MSK   0x03FF
#define LSB11_MSK   0x07FF
#define LSB12_MSK   0x0FFF
#define LSB13_MSK   0x1FFF
#define LSB14_MSK   0x3FFF
#define LSB15_MSK   0x7FFF
#define LSB16_MSK   0xFFFF

#define MOD2_MSK    LSB1_MSK
#define MOD4_MSK    LSB2_MSK
#define MOD8_MSK    LSB3_MSK
#define MOD16_MSK   LSB4_MSK
#define MOD32_MSK   LSB5_MSK
#define MOD64_MSK   LSB6_MSK
#define MOD128_MSK  LSB7_MSK



/* -- DSMCC DEFINES */

/* NB. All offsets assume that variable length fields are zero length */

/* -- DSMCC section header defines */
#define DSIDII_ID               0x3B
#define DDB_ID                  0x3C
#define STREAM_DESCR_ID         0x3D

#define SECTION_HDR_LEN         8
#define MIN_SECTION_LEN         9
#define MAX_SECTION_LEN         4093

#define MAX_DDB_BLOCKSIZE       4066

/* -- DSMCC Message Header (dsmccMessageHeader) defines */
#define DSMCC_MSG_HDR_LEN       12

/* -- DSI Message defines */
#define DSI_HDR_LEN             24
#define MIN_SRG_INFO_LEN        (IOR_HDR_LEN + \
                                 PROFILE_TAG_BIOP_HDR_LEN + \
                                 MIN_PROFILE_TAG_BIOP_DATA_LEN)
#define MIN_DSI_MSG_BODY_LEN    (DSI_HDR_LEN + \
                                 MIN_SRG_INFO_LEN)
#define MIN_DSI_MSG_LEN         (DSMCC_MSG_HDR_LEN + \
                                 MIN_DSI_MSG_BODY_LEN)

/* -- DII Message defines */

#define MIN_DII_MSG_BODY_LEN    20
#define MIN_DII_MSG_LEN         (DSMCC_MSG_HDR_LEN + \
                                 MIN_DII_MSG_BODY_LEN)

/* -- DDB message defines */
#define DSMCC_DOWNLOAD_HDR_LEN              12
#define DDB_MSG_PAYLOAD_HDR_LEN             6
#define MIN_DDB_PAYLOAD_DATA_LEN            0
#define MIN_DDB_MSG_BODY_LEN                (DDB_MSG_PAYLOAD_HDR_LEN + \
                                             MIN_DDB_PAYLOAD_DATA_LEN)
#define MIN_DDB_MSG_LEN                     (DSMCC_DOWNLOAD_HDR_LEN  + \
                                             MIN_DDB_MSG_BODY_LEN)
#define MAX_DDB_BLOCKSIZE                   4066

/* DSMCC Masks */
#define TRANSACTION_ID_UPDATED_MASK 0x00000001
#define TRANSACTION_ID_IDENT_MASK   0x0000fffe
#define TRANSACTION_ID_VERSION_MASK 0x3fff0000
#define TRANSACTION_ID_ORIG_MASK    0xc0000000

/* DSM-CC Object header defines */
#define OBJECT_NUMBYTES_TO_MESSAGE_START    12
#define BIOP_MAGIC                          0x42494F50

/* DSMCC Profile Tags */
#define TAG_LITE_OPTIONS            0x49534f05
#define TAG_BIOP                    0x49534f06
#define TAG_CONN_BINDER             0x49534f40
#define TAG_SERVICE_LOCATION        0x49534f46
#define TAG_OBJECT_LOCATION         0x49534f50

/* IOP::IOR defines */
#define IOR_HDR_LEN                 12

/* BIOP::ProfileBody defines */
#define PROFILE_TAG_BIOP_HDR_LEN        10
#define MIN_PROFILE_TAG_BIOP_DATA_LEN   (MIN_OBJ_LOCATION_LEN + \
                                         MIN_CONN_BINDER_LEN)

/* BIOP::ProfileBody - LiteOptionComponent defines */
#define MIN_OBJ_LOCATION_LEN            15
#define MIN_OBJLOC_COMPONENT_DATA_LEN   (MIN_OBJ_LOCATION_LEN - 5)
#define MIN_CONN_BINDER_LEN             23
#define MIN_CONBIND_COMPONENT_DATA_LEN  (MIN_CONN_BINDER_LEN - 5)


/* Tap use constants */
#define UNKNOWN_USE              ((U16BIT) 0)
#define MPEG_TS_UP_USE           ((U16BIT) 1)  /* MPEG transport upstream from Client */
#define MPEG_TS_DOWN_USE         ((U16BIT) 2)  /* MPEG transport downstream to Client */
#define MPEG_ES_UP_USE           ((U16BIT) 3)  /* MPEG elementary upstream from Client */
#define MPEG_ES_DOWN_USE         ((U16BIT) 4)  /* MPEG elementary downstream to Client */
#define DOWNLOAD_CTRL_USE        ((U16BIT) 5)  /* control request/response */
#define DOWNLOAD_CTRL_UP_USE     ((U16BIT) 6)  /* control request from Client */
#define DOWNLOAD_CTRL_DOWN_USE   ((U16BIT) 7)  /* control response to Client */
#define DOWNLOAD_DATA_USE        ((U16BIT) 8)  /* data request/response */
#define DOWNLOAD_DATA_UP_USE     ((U16BIT) 9)  /* data response upstream from Client */
#define DOWNLOAD_DATA_DOWN_USE   ((U16BIT) 10) /* data block downstream to Client */
#define STR_NPT_USE              ((U16BIT) 11) /* NPT Descriptors */
#define STR_STATUS_AND_EVENT_USE ((U16BIT) 12) /* Stream Mode and Event Descriptors */
#define STR_EVENT_USE            ((U16BIT) 13) /* Stream Event Descriptor */
#define STR_STATUS_USE           ((U16BIT) 14) /* Stream Mode Descriptor */
#define RPC_USE                  ((U16BIT) 15) /* RPC bi-directional */
#define IP_USE                   ((U16BIT) 16) /* IP bi-directional */
#define SDB_CTRL_USE             ((U16BIT) 17) /* control channel for Switched Digital Broadcast */
#define T120_TAP1                ((U16BIT) 18) /* reserved for use and definition by T.120 */
#define T120_TAP2                ((U16BIT) 19) /* reserved for use and definition by T.120 */
#define T120_TAP3                ((U16BIT) 20) /* reserved for use and definition by T.120 */
#define T120_TAP4                ((U16BIT) 21) /* reserved for use and definition by T.120 */
#define BIOP_DELIVERY_PARA_USE   ((U16BIT) 22) /* Module delivery parameters */
#define BIOP_OBJECT_USE          ((U16BIT) 23) /* BIOP objects in Modules */
#define BIOP_ES_USE              ((U16BIT) 24) /* Elementary Stream */
#define BIOP_PROGRAM_USE         ((U16BIT) 25) /* Program */
#define BIOP_DNL_CTRL_USE        ((U16BIT) 26) /* Download control messages */

/* -- objectKind and IOR typeId strings */
#define SRG_STR 0x73726700 /* = "srg\0" */
#define DIR_STR 0x64697200 /* = "dir\0" */
#define FIL_STR 0x66696c00 /* = "fil\0" */
#define STR_STR 0x73747200 /* = "str\0" */
#define STE_STR 0x73746500 /* = "ste\0" */

/* DSMCC Descriptor Tag found in DII moduleInfo and DSI groupInfo */
#define DESCRIPTOR_TYPE_TAG                 ((U8BIT) 1)
#define DESCRIPTOR_NAME_TAG                 ((U8BIT) 2)
#define DESCRIPTOR_INFO_TAG                 ((U8BIT) 3)
#define DESCRIPTOR_MODULE_LINK_TAG          ((U8BIT) 4) /* DII only */
#define DESCRIPTOR_CRC32_TAG                ((U8BIT) 5) /* DII only */
#define DESCRIPTOR_LOCATION_TAG             ((U8BIT) 6)
#define DESCRIPTOR_EST_DOWNLOAD_TIME_TAG    ((U8BIT) 7)
#define DESCRIPTOR_GROUP_LINK_TAG           ((U8BIT) 8) /* DSI only */
#define DESCRIPTOR_COMP_MODULE_TAG          ((U8BIT) 9) /* DII only */
#define DESCRIPTOR_MHP_LABEL                ((U8BIT) 0x70) /* DII only */
#define DESCRIPTOR_MHP_CACHING_PRIORITY     ((U8BIT) 0x71) /* DII only */


/* -- MHEG Profile specific (generally useful) defines */

/* -- Settings for UK MHEG profile 1 = 64 + 1 for null (v1.05, sections 3.11 and 8.3.3.3) */
/* -- BUT Settings for MHP = 254 + 1 for null (ETSI 101 812 (7/2000) section 14.1.4) */
#define MAX_PATH_NAME_SIZE      255     /* -- Including null terminator */

/* -- NB. Smallest path element length is one char + one seperator char
   --     (eg. a/). Subtract one from MAX_PATH_NAME_SIZE for null
   --     terminator and add one to force a round up (since there may
   --     be no seperator char at start) */
#define MAX_DIRECTORY_DEPTH     (((MAX_PATH_NAME_SIZE - 1) + 1) / 2)


/* -- Implementation specific defines */

/* -- Path seperator used for internal path represention only */
#define PATH_SEPERATOR_CHAR     '/'

/* -- Min contiguous memory bytes at start of mem mgr block/mem area */
#define MIN_MEM_BLK_SIZE    256

/* -- Restricted to keep ModuleBuilder_t within MIN_MEM_BLK_SIZE
   -- Currently allows max broadcast (compressed) module size of 3.2MBytes */
#define MAX_BLOCKS_IN_MODULE        1600

/*** TODO: CHECK THIS IS SUFFICIENT IN ALL CASES ***/
#define NUM_INTERNAL_MEM_SEQ_MAX    128

/* -- Number of module acquisition (& decompress) attempts that will be
   -- made before giving up */
#define MAX_MODULE_DECOMPRESS_FAILURES  3


/*
-- Section filter defines
--
-- NOTES:
-- To help detect sections supplied from old (deleted) filters, make section
-- filter heap bigger than max filters so memory not re-used immediately.
--
*/
#define SECTION_FILTER_HEAP_SLACK   16
#define SECTION_FILTER_HEAP_SIZE    (NUM_SECTION_FILTERS_MAX_DEFAULT + \
                                     SECTION_FILTER_HEAP_SLACK)


/*
-- zlib heap size defines (for moduleDecompress)
*/
/* -- TODO: check 32K (was 16K) is always sufficient extra heap
        OR: pass zlib alloc funcs via core API so platform layer can decide
            where to get zlib memory */
/* RJH largest allocation yet seen is around 40k. Also some non-stack behaviour
   seen, resulting in external fragmentation.
   64k (32k window size + 32k extra) is probably a reasonable size for now,
   but REVISIT */
#define ZLIB_HEAP_NUM_BYTES (((U32BIT)1 << 15 /*MAX_WBITS*/ ) + (1024*32/*16*/))
#define ZLIB_HEAP_NUM_WORDS ((ZLIB_HEAP_NUM_BYTES + 3) >> 2)


/* Object Carousel Linked List IDs */
#define OBJECT_CAROUSEL_LIST        0

#define NUM_LISTS_OBJECT_CAROUSEL   1


/* Data Carousel Linked List IDs */
#define OC_DATA_CAROUSEL_LIST       0
#define OC_DII_ACQUIRE_LIST         1

#define OC_LITE_OBJECT_LOAD_LIST    0
#define NUM_LITE_OBJECT_LOAD_LIST   1

#define NUM_LISTS_DATA_CAROUSEL     2


/* Module Linked List IDs */
#define DC_MODULE_LIST              0
#define OC_MODULE_ACQUIRE_LIST      1
#define MODULE_PRIORITY_LIST        2
#define MODULE_LOADED_LIST          2
#define MODULE_DELETE_LIST          2

#define NUM_LISTS_MODULE            3


/* Object Linked List IDs */
#define CURR_OBJECT_LIST            0
#define MODULE_OBJECT_LIST          1   /* -- Currently not used */

#define NUM_LISTS_OBJECT            2


/* Load Request Linked List IDs */
#define CURR_LOAD_REQUEST_LIST      0
#define MODULE_LOAD_REQUEST_LIST    1

#define NUM_LISTS_LOAD_REQUEST      2

/* SI Query Linked List IDs */
#define CURR_SI_QUERY_LIST          0
#define DUPLICATE_SI_QUERY_LIST     1

#define NUM_LISTS_SI_QUERY          2

/*
-- General purpose debug check and action macro (disabled by NDEBUG)
--
-- condn        = valid condition to be checked for error (eg. err == CLDSM_OK )
-- dbgErrActn   = command(s) to execute on error condition in debug builds
*/

#ifdef NDEBUG
    #define DEBUG_CHK( condn, dbgActn )
#else
    #define DEBUG_CHK( condn, dbgActn )     if (!( condn )) { dbgActn; }
#endif



/*
-- Macro to provide API parameter checking that can be disabled in retail
-- builds if required (via DSM_NO_API_PARAM_CHECK)
--
-- API parameter checking in retail builds is enabled by default (ie. if
-- DSM_NO_API_PARAM_CHECK is not defined).
--
-- condn        = valid condition to be checked for error (eg. err == CLDSM_OK )
-- dbgErrActn   = command(s) to execute on error condition in debug builds
-- relErrActn   = command(s) to execute on error condition in all builds
--                *** NB. dbgErrActn always executed before relErrActn ***
--
*/
#ifdef DSM_NO_API_PARAM_CHECK

    /* -- API parameter checking in debug builds only */

    #ifdef NDEBUG

        #define API_PARAM_CHK( condn, dbgErrActn, relErrActn )

    #else

        #define API_PARAM_CHK( condn, dbgErrActn, relErrActn )  \
            if (!( condn )) { dbgErrActn; }                     \

    #endif

#else

    /* -- API parameter checking in all builds (default) */

    #define API_PARAM_CHK( condn, dbgErrActn, relErrActn )      \
        if (!( condn )) { dbgErrActn; relErrActn; }             \

#endif



/*
-- These macro definitions provide three 'priority' levels (0, 1, 2) of
-- general purpose data error checking.
-- The highest priority (0) is always performed and cannot be disabled, the
-- lower two priorities can be optionally disabled for retail mode (at compile
-- time).
--
-- The lower priority levels (2 or 1 & 2) can be enabled/disabled for retail
-- builds (via DSM_DATA_CHECK_LEVEL).
--
-- Both lower levels (1 & 2) of checking are always enabled in debug mode
--
-- The default data check level in retail builds is level 1 (ie. if
-- DSM_DATA_CHECK_LEVEL is not defined).
--
-- Syntax is:
-- L<level>_DATA_CHK( condn, dbgErrActn, relErrActn )
--
-- <lvl>    = 1 - Level 1 priority checking only
-- <lvl>    = 2 - Level 1 and level 2 checking
--
-- condn        = valid condition to be checked for error (eg. err == CLDSM_OK )
-- dbgErrActn   = command(s) to execute on error condition in debug builds
-- relErrActn   = command(s) to execute on error condition in all builds
--                *** NB. dbgErrActn always executed before relErrActn ***
--
*/
#if !defined(DSM_DATA_CHECK_LEVEL)
    #define DSM_DATA_CHECK_LEVEL    1
#endif


/* -- Level 0 data checking always performed */

#define L0_DATA_CHK( condn, dbgErrActn, relErrActn )    \
    if (!( condn )) { dbgErrActn; relErrActn; }         \


#if DSM_DATA_CHECK_LEVEL >= 1

    /* -- Level 1 data checking in all builds (default) */

    #define L1_DATA_CHK( condn, dbgErrActn, relErrActn )    \
        if (!( condn )) { dbgErrActn; relErrActn; }         \

#else

    /* -- Level 1 data checking in debug builds only */

    #if (defined(NDEBUG) || defined(DSM_PROFILING_BUILD))

        #define L1_DATA_CHK( condn, dbgErrActn, relErrActn )

    #else

        #define L1_DATA_CHK( condn, dbgErrActn, relErrActn )\
            if (!( condn )) { dbgErrActn; }                 \

    #endif

#endif


#if DSM_DATA_CHECK_LEVEL >= 2

    /* -- Level 2 data checking in all builds */

    #define L2_DATA_CHK( condn, dbgErrActn, relErrActn )    \
        if (!( condn )) { dbgErrActn; relErrActn; }         \

#else

    /* -- Level 2 data checking in debug builds only (default) */

    #if (defined(NDEBUG) || defined(DSM_PROFILING_BUILD))

        #define L2_DATA_CHK( condn, dbgErrActn, relErrActn )

    #else

        #define L2_DATA_CHK( condn, dbgErrActn, relErrActn )\
            if (!( condn )) { dbgErrActn; }                 \

    #endif

#endif



/* In debug only, this macro checks for error codes returned from memory API
   functions */
#ifndef NDEBUG
#define CHECK_MEM_ERR( func )                           \
    {                                                   \
        E_DsmMemErr memErr;                                  \
                                                        \
        memErr = func;                                  \
        if (memErr != MEM_NO_ERR) {                     \
            dsmDP1(( "Memory error : %i \n", memErr )); \
            dsmAssert(( memErr == MEM_NO_ERR ));        \
        }                                               \
    }

#else
#define CHECK_MEM_ERR( x ) x
#endif


/*---Enumerations for public use---------------------------------------------*/

/*---Global type defs for public use-----------------------------------------*/


/* General DSMCC types */

typedef U8BIT ModuleVersion_t;


/* Object Location Types */
typedef struct {
    U8BIT   length;
    U8BIT   data[4];
} ObjectKey_t , *pObjectKey_t;


typedef struct {
    U32BIT      carouselId;
    U16BIT      moduleId;
    ObjectKey_t objectKey;
  U32BIT        uiBindingTag;
  U8BIT  dvbCarouselNSAPaddress[20];
  S8BIT  pathName[65];// TODO use [MAX_PATH_NAME_SIZE];
} ObjectLocation_t, *pObjectLocation_t;


/* Tap Types */
typedef struct {
    /* use = BIOP_DELIVERY_PARA_USE */
    U16BIT  id;
    U16BIT  associationTag;
    U32BIT  transactionId;
    U32BIT  timeout;
} DeliveryParaTap_t, *pDeliveryParaTap_t;


typedef struct {
    /* use = BIOP_OBJECT_USE */
    U16BIT id;
    U16BIT associationTag;
} ObjectTap_t, *pObjectTap_t;


typedef struct s_LLControl *P_LLControl;
typedef struct s_se_info* ps_se_info;

typedef struct s_ObjectCarousel *pObjectCarousel_t;
typedef struct s_Module  *pModule_t;

/*
-- Structure type for DSM-CC Core Layer instance data
*/

typedef struct _clDsmInstanceHandle_struct {

    /* -- SETUP DATA (COPY) */
    clDsmSetup_t    setup;


    /* -- Recursion depth counters for specific functions */
    U32BIT  pfrdoCallDepth;     /* -- For preFetchRelativeDirObj() */
    U32BIT  pfdlfCallDepth;     /* -- For preFetchDirLoadFinalise() */
    U32BIT  pfsdndCallDepth;    /* -- For preFetchSubDirsAndNewDIIsFromLoadedDir() */

    /* -- Store for memory manager context (from memStart) */
    void*   memContext;

    /* -- Store for current service info */
    S_DvbLocator dvbLocator;
    BOOLEAN    currentServiceSet;
    BOOLEAN    cacheFull;

    /* -- Generation counter for siQuery results and sections */
    U32BIT  generationCount;

    /* -- Store for SI query results */
    BOOLEAN    lastPIDResultStored;
    U16BIT  lastServiceId;
    U16BIT  lastAssociationTag;
    U16BIT  lastPID;

    /* -- Store of number of objects currently opened by clients */
        /* TODO: Should be stored in OC when multi-carousel supported */
    U32BIT      dsmObjectsOpen;

    /* -- Handle to section filter heap memory */
    void*       sectionFilterHeap;

    /* -- zlib heap memory (for module decompress) */
    /* TODO: malloc this in moduleDecompressInit ? */
    U32BIT*  zlibHeapPtr;
    U32BIT*  zlibHeapTop;
    U32BIT   zlibHeap[ ZLIB_HEAP_NUM_WORDS ];

    pObjectCarousel_t pCurrentCarousel;
    pObjectCarousel_t pBootingCarousel;

    P_LLControl   llcObjectCarousels;
    P_LLControl   llcModulePriority;
    P_LLControl   llcLoadedModules;
    P_LLControl   llcExpiredModules;
    P_LLControl   llcCurrObjects;
    P_LLControl   llcCurrLoadRequests;
    P_LLControl   llcCurrSiQueries;

    ps_se_info  hSubscribedEventList;

} clDsmInstData_t, *pclDsmInstData_t;

typedef struct _clDsmTimerManagement_struct {

    void*    mainTimerHandle;
    void*    nextTimerHandle;
    U32BIT   mainDuration;
    U32BIT   nextDuration;

} clDsmTimerManagement_t, *pclDsmTimerManagement_t;

/*------------------------------  Exported Data  -----------------------------*/


/*---------------------------  Exported Prototypes  --------------------------*/

clDsmErr_t clDsmUnloadAllObjects( clDsmInstHandle_t instance, E_DsmRstMode mode );

/*----------------------------------------------------------------------------*/

#ifdef __cplusplus
}
#endif
#endif /* _CLDSMSYSTEM_H_ */