1    /* 
     2     * Copyright (c) 2010, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * 
    32     */
    33    /*!
    34     *  ======== ICodec ========
    35     *  Codec Engine algorithm interface
    36     *
    37     *  All codecs supported by the codec engine must implement this interface.
    38     *  This interface provides the Codec Engine runtime the following information:
    39     *  @p(nlist)
    40     *      - How much stack space is required by the algorithm during instance
    41     *        creation (so the runtime can allocate an appropriate stack).
    42     *      - How much stack space is required by the algorithm during execution
    43     *        (so the runtime can allocate an appropriate stack).
    44     *      - The algorithm's entry points for the IALG interface (so the runtime
    45     *        can lookup the algorithm's functions based on a string name).
    46     *      - The algorithm's entry points for the optional IDMA3 interface
    47     *        (so the runtime can allocate DMA resources for the algorithm at
    48     *         runtime).
    49     *      - The entry points for "stubs" and "skeletons" in the case that the
    50     *        algorithm is to be run on a remote processor.
    51     *      - The size of scratch memory required by the algorithm.
    52     *  @p
    53     */
    54    metaonly interface ICodec
    55    {
    56        /*!
    57         *  ======== isLocal ========
    58         *  Require this codec to run "locally"
    59         *
    60         *  This configuration parameter determines whether or not the
    61         *  application requires the codec's library in order to link.
    62         *  For example, this parameter is set to false in the case that
    63         *  the application is running on a different CPU than the codec.
    64         *
    65         *  @_nodoc
    66         */
    67        config Bool isLocal = true;
    68    
    69        /*!
    70         *  ======== ialgFxns ========
    71         *  Name of xDAIS alg function table
    72         *
    73         *  All xDAIS algorithms must define an IALG_Fxns structure that
    74         *  contains implementations of the IALG methods.  This configuration
    75         *  parameter is simply the extern name of this structure.
    76         */
    77        readonly config String ialgFxns;
    78    
    79        /*!
    80         *  ======== idma3Fxns ========
    81         *  Name of xDAIS alg IDMA3 Interface function table
    82         *
    83         *  All xDAIS algorithms that use DMA must define an IDMA3_Fxns structure
    84         *  containing the pointers to functions implementatng the IDMA3 interface.
    85         *  If algorithm does not use DMA this structure does not have to be
    86         *  defined.
    87         *
    88         *  This configuration parameter is simply the extern name of this
    89         *  structure when defined, null otherwise.
    90         */
    91        readonly config String idma3Fxns;
    92    
    93        /*!
    94         *  ======== iresFxns ========
    95         *  Name of xDAIS alg IRES Interface function table
    96         *
    97         *  All xDAIS algorithms that use an IRES resource must define an
    98         *  IRES_Fxns structure containing the pointers to functions
    99         *  implementatng the IRES interface.
   100         *  If algorithm does not use an IRES resource this structure does not
   101         *  have to be defined.
   102         *
   103         *  This configuration parameter is simply the extern name of this
   104         *  structure when defined, null otherwise.
   105         *
   106         *  @see #ialgFxns
   107         *  @see #idma3Fxns
   108         */
   109        readonly config String iresFxns;
   110    
   111        /*!
   112         *  ======== serverFxns ========
   113         *  Name of skeleton fxn table
   114         *
   115         *  All algorithm's that can run on a remote processor must specify a set
   116         *  of "stub" functions that marshall arguments to send to the remote
   117         *  process that runs corresponding "skeletons" to do the actual
   118         *  processing.  This configuration parameter defines the entry point for
   119         *  this algorithm's the skeletons (which run on the remote processor).
   120         *
   121         *  This is generally not configured by application or server config
   122         *  scripts, but rather by developers of VISA-like API class extensions.
   123         *  However, an application or server integrator could use this config
   124         *  param to configure in custom serverFxns.
   125         *
   126         *  @see #stubFxns
   127         */
   128        config String serverFxns;
   129    
   130        /*!
   131         *  ======== stubFxns ========
   132         *  Name of stubs fxn table
   133         *
   134         *  All algorithm's that can run on a remote processor must specify a set
   135         *  of "stub" functions that marshall arguments to send to the remote
   136         *  process that runs corresponding "skeletons" to do the actual
   137         *  processing.  This configuration parameter defines the entry point for
   138         *  this algorithm's the stubs (which run on the local processor).
   139         *
   140         *  This is generally not configured by application or server config
   141         *  scripts, but rather by developers of VISA-like API class extensions.
   142         *  However, an application or server integrator could use this config
   143         *  param to configure in custom stubFxns.
   144         *
   145         *  @see #serverFxns
   146         */
   147        config String stubFxns;
   148    
   149        /*!
   150         *  ======== rpcProtocolVersion ========
   151         *  Version of the Protocol used between the stubFxns and the serverFxns.
   152         *
   153         *  This is set by a particular implementation of a stub/skeleton RPC pair,
   154         *  and is used at runtime to ensure the protocol matches.  This is
   155         *  important, for example, to ensure that the protocol used by skeletons
   156         *  built into a server matches that used by the stubs built into the
   157         *  application.  Specifically, this is typically changed when the
   158         *  marshalling/unmarshalling message format changes.
   159         *
   160         *  This is generally not configured by application or server config
   161         *  scripts, but rather by developers of VISA-like API class extensions.
   162         *
   163         *  This rpcProtocolVersion is built into the local application executable,
   164         *  as well as the remote server's executable.
   165         *
   166         *  Developers of class extensions should ensure this config parameter is
   167         *  set appropriately by each release of their stubs/skeletons.  If a new
   168         *  protocol is introduced, implying that updating both would result in
   169         *  error, the number should be incremented.
   170         *
   171         *  There is no "backward-compatibility" requirement in rpcProtocolVersion.
   172         *  If the version is different, regardless of whether it's larger or
   173         *  smaller, the creation of algorithms of this class will fail.
   174         */
   175        readonly config Int rpcProtocolVersion;
   176    
   177        /*!
   178         *  ======== uuid =======
   179         *  Unique algorithm implementation ID
   180         *
   181         *  This integer must be a unique ID for every algorithm in a "system",
   182         *  where the "system" includes all possible DSP Servers.
   183         *
   184         *  This id is used by the Codec Engine APIs to identify the algorithm
   185         *  implementation that will create an instance on a DSP Server.
   186         *
   187         *  If a codec doesn't explicitly configure this parameter, a "very likely
   188         *  unique" ID will be generated.  It is recommended that codecs not
   189         *  explicitly configure this parameter, and leave it to the system.
   190         */
   191        config Int uuid;
   192    
   193        /*!
   194         *  ======== frameRate ========
   195         *  Smallest supported frame rate (frames / second)
   196         *
   197         *  This is used to compute a default priority assignment for algorithm
   198         *  threads in a DSP Server.
   199         *
   200         *  @_nodoc
   201         */
   202        readonly config Int frameRate;
   203    
   204        /*!
   205         *  ======== codecClassConfigurable ========
   206         *  True if the class to which the codec belongs (VISA, or custom if not
   207         *  a VISA) has some special run-time config params
   208         *
   209         *  @_nodoc
   210         */
   211        readonly config Bool codecClassConfigurable;
   212    
   213        /*!
   214         *  ======== useCache ========
   215         *  If set to true, the codec's memory requests will be allocated from
   216         *  cacheable memory. If set to false, the memory will be allocated from
   217         *  non-cached memory. If this is not set, the
   218         *  ti.sdo.ce.alg.Settings.useCache flag will determine whether the
   219         *  codec's memory will be allocated from cached or non-cached memory.
   220         */
   221        config Bool useCache;
   222    
   223        /*!
   224         *  ======== getCreationStackSize ========
   225         *  Get the maximum required stack size (in octets) for this algorithm
   226         *  during algorithm instance creation.
   227         *
   228         *  This method is called during DSP Server configuration and is used to
   229         *  ensure that the instance creation thread on the server has sufficient
   230         *  stackspace to instantiate the algorithm.  This stack size is typically
   231         *  the greater of the stack sizes required by the algorithm's
   232         *  algNumAlloc(), algAlloc(), or algInit() methods.
   233         */
   234        Int getCreationStackSize(xdc.cfg.Program.Module prog);
   235    
   236        /*!
   237         *  ======== getDaramScratchSize ========
   238         *  Get the maximum scratch size (in octets) required for this algorithm
   239         *  from DARAM space.
   240         *
   241         *  This method is called during DSP Server configuration and is used to
   242         *  ensure that sufficient scratch space is configured for the specified
   243         *  set of algorithms.
   244         */
   245        Int getDaramScratchSize(xdc.cfg.Program.Module prog);
   246    
   247        /*!
   248         *  ======== getSaramScratchSize ========
   249         *  Get the maximum scratch size (in octets) required for this algorithm
   250         *  from SARAM space.
   251         *
   252         *  This method is called during DSP Server configuration and is used to
   253         *  ensure that sufficient scratch space is configured for the specified
   254         *  set of algorithms.
   255         */
   256        Int getSaramScratchSize(xdc.cfg.Program.Module prog);
   257    
   258        /*!
   259         *  ======== getStackSize ========
   260         *  Get the maximum stack size (in octets) required for this algorithm
   261         *  during its execution phase.
   262         *
   263         *  This method is called during DSP Server configuration and is used to
   264         *  ensure that threads on the server have sufficient stackspace to run
   265         *  the algorithm.
   266         */
   267        Int getStackSize(xdc.cfg.Program.Module prog);
   268    
   269        /*!
   270         *  ======== getUUID ========
   271         *  Get a uuid for this codec
   272         *
   273         *  This method is used to get the uuid rather than reading the uuid
   274         *  config parameter; this allows the algorithm producer to let the
   275         *  system generate a uuid from the algorithm's name.
   276         *
   277         *  Individual algorithm's should not implement this methods; the default
   278         *  (base) implementation provided in the ti.sdo.ce package should be
   279         *  sufficient.
   280         *
   281         *  @_nodoc
   282         */
   283        Int getUUID();
   284    }
   285    /*
   286     *  @(#) ti.sdo.ce; 1, 0, 6,432; 12-2-2010 21:19:08; /db/atree/library/trees/ce/ce-r11x/src/ xlibrary
   287    
   288     */
   289