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