1    /* 
     2     * Copyright (c) 2009, 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         *  ======== getCreationStackSize ========
   215         *  Get the maximum required stack size (in octets) for this algorithm
   216         *  during algorithm instance creation.
   217         *
   218         *  This method is called during DSP Server configuration and is used to
   219         *  ensure that the instance creation thread on the server has sufficient
   220         *  stackspace to instantiate the algorithm.  This stack size is typically
   221         *  the greater of the stack sizes required by the algorithm's
   222         *  algNumAlloc(), algAlloc(), or algInit() methods.
   223         */
   224        Int getCreationStackSize(xdc.cfg.Program.Module prog);
   225    
   226        /*!
   227         *  ======== getDaramScratchSize ========
   228         *  Get the maximum scratch size (in octets) required for this algorithm
   229         *  from DARAM space.
   230         *
   231         *  This method is called during DSP Server configuration and is used to
   232         *  ensure that sufficient scratch space is configured for the specified
   233         *  set of algorithms.
   234         */
   235        Int getDaramScratchSize(xdc.cfg.Program.Module prog);
   236    
   237        /*!
   238         *  ======== getSaramScratchSize ========
   239         *  Get the maximum scratch size (in octets) required for this algorithm
   240         *  from SARAM space.
   241         *
   242         *  This method is called during DSP Server configuration and is used to
   243         *  ensure that sufficient scratch space is configured for the specified
   244         *  set of algorithms.
   245         */
   246        Int getSaramScratchSize(xdc.cfg.Program.Module prog);
   247    
   248        /*!
   249         *  ======== getStackSize ========
   250         *  Get the maximum stack size (in octets) required for this algorithm
   251         *  during its execution phase.
   252         *
   253         *  This method is called during DSP Server configuration and is used to
   254         *  ensure that threads on the server have sufficient stackspace to run
   255         *  the algorithm.
   256         */
   257        Int getStackSize(xdc.cfg.Program.Module prog);
   258    
   259        /*!
   260         *  ======== getUUID ========
   261         *  Get a uuid for this codec
   262         *
   263         *  This method is used to get the uuid rather than reading the uuid
   264         *  config parameter; this allows the algorithm producer to let the
   265         *  system generate a uuid from the algorithm's name.
   266         *
   267         *  Individual algorithm's should not implement this methods; the default
   268         *  (base) implementation provided in the ti.sdo.ce package should be
   269         *  sufficient.
   270         *
   271         *  @_nodoc
   272         */
   273        Int getUUID();
   274    }
   275    /*
   276     *  @(#) ti.sdo.ce; 1, 0, 6,389; 12-18-2009 17:39:30; /db/atree/library/trees/ce/ce-o06x/src/
   277     */
   278