1    /* 
     2     * Copyright (c) 2012, 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         *  Flag indicating whether there are 'special' runtime config params
   207         *
   208         *  True if the class to which the codec belongs (VISA, or custom if not
   209         *  a VISA) has some special run-time config params
   210         *
   211         *  @_nodoc
   212         */
   213        readonly config Bool codecClassConfigurable;
   214    
   215        /*!
   216         *  ======== useCache ========
   217         *  Flag indicating whether the framework should provide cached memory
   218         *
   219         *  If set to true, the alg's memory requests will be allocated from
   220         *  cacheable memory.  If set to false, the memory will be allocated from
   221         *  non-cached memory. If left unset, the
   222         *  ti.sdo.ce.alg.Algorithm.useCache flag will determine whether the
   223         *  alg's memory will be allocated from cached or non-cached memory.
   224         */
   225        config Bool useCache;
   226    
   227        /*!
   228         *  ======== getCreationStackSize ========
   229         *  Get the maximum required stack size (in octets) for this algorithm
   230         *  during algorithm instance creation.
   231         *
   232         *  This method is called during DSP Server configuration and is used to
   233         *  ensure that the instance creation thread on the server has sufficient
   234         *  stackspace to instantiate the algorithm.  This stack size is typically
   235         *  the greater of the stack sizes required by the algorithm's
   236         *  algNumAlloc(), algAlloc(), or algInit() methods.
   237         */
   238        Int getCreationStackSize(xdc.cfg.Program.Module prog);
   239    
   240        /*!
   241         *  ======== getDaramScratchSize ========
   242         *  Get the maximum scratch size (in octets) required for this algorithm
   243         *  from DARAM space.
   244         *
   245         *  This method is called during DSP Server configuration and is used to
   246         *  ensure that sufficient scratch space is configured for the specified
   247         *  set of algorithms.
   248         */
   249        Int getDaramScratchSize(xdc.cfg.Program.Module prog);
   250    
   251        /*!
   252         *  ======== getSaramScratchSize ========
   253         *  Get the maximum scratch size (in octets) required for this algorithm
   254         *  from SARAM space.
   255         *
   256         *  This method is called during DSP Server configuration and is used to
   257         *  ensure that sufficient scratch space is configured for the specified
   258         *  set of algorithms.
   259         */
   260        Int getSaramScratchSize(xdc.cfg.Program.Module prog);
   261    
   262        /*!
   263         *  ======== getStackSize ========
   264         *  Get the maximum stack size (in octets) required for this algorithm
   265         *  during its execution phase.
   266         *
   267         *  This method is called during DSP Server configuration and is used to
   268         *  ensure that threads on the server have sufficient stackspace to run
   269         *  the algorithm.
   270         */
   271        Int getStackSize(xdc.cfg.Program.Module prog);
   272    
   273        /*!
   274         *  ======== getUUID ========
   275         *  Get a uuid for this codec
   276         *
   277         *  This method is used to get the uuid rather than reading the uuid
   278         *  config parameter; this allows the algorithm producer to let the
   279         *  system generate a uuid from the algorithm's name.
   280         *
   281         *  Individual algorithm's should not implement this methods; the default
   282         *  (base) implementation provided in the ti.sdo.ce package should be
   283         *  sufficient.
   284         *
   285         *  @_nodoc
   286         */
   287        Int getUUID();
   288    }
   289    /*
   290     *  @(#) ti.sdo.ce; 1, 0, 6,1; 1-17-2012 23:09:32; /db/atree/library/trees/ce/ce-t03/src/ xlibrary
   291    
   292     */
   293