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     *  ======== Engine ========
    35     *  Engine Configuration interface
    36     */
    37    @Template("./Engine.xdt")
    38    
    39    metaonly module Engine {
    40    
    41        /*!
    42         *  ======== local ========
    43         *  Default engine used by clients of the VISA API's that pass NULL for
    44         *  the engine handle
    45         *
    46         *  @_nodoc
    47         */
    48        config Engine.Instance local;
    49    
    50        /*!
    51         *  ======== MAXGROUPID ========
    52         *  Maximum group id.
    53         */
    54        const Int MAXGROUPID = 20;
    55    
    56    
    57       /*!
    58         *  ======== initFromServer ========
    59         *  Allow alg tables of engines with a remote server to be populated by
    60         *  querying the server.
    61         */
    62        config Bool initFromServer = true;
    63    
    64        /*!
    65         *  ======== AlgDesc ========
    66         *  Algorithm descriptor
    67         *
    68         *  Each engine "contains" multiple algorithms described by AlgDesc
    69         *  structures.
    70         *
    71         *  @field(name)    This string specifies the "local" name used by the
    72         *                  application to identify the algorithm to instantiate
    73         *  @field(mod)     This field is a module reference that identifies the
    74         *                  actual module implementing the algorithm to instantiate
    75         *  @field(local)   If true, the algorithm should be instantiated on the
    76         *                  "local" CPU; otherwise the server will create an
    77         *                  instance of the algorithm identifed by `mod`.
    78         *  @field(groupId) This id specifies which resource sharing group
    79         *                  this codec will be placed into.  This 'group' concept
    80         *                  is used by the framework to ensure algorithms in the
    81         *                  same group don't pre-empt each other and corrupt the
    82         *                  shared resources.
    83         *
    84         *                  Note that this parameter is ignored if `local` is not
    85         *                  TRUE.
    86         */
    87        struct AlgDesc {
    88            String          name;       /*! Alg nick-name */
    89            ICodec.Module   mod;        /*! The alg implementation */
    90            Bool            local;      /*! Run algorithm locally */
    91            Int             groupId;    /*! Alg group ID for sharing resources */
    92        };
    93    
    94        /*!
    95         *  ======== createFromServer ========
    96         *  Create an Engine from a Server package
    97         *
    98         *  Given a Server package and an executable in that package, this method
    99         *  creates an Engine instance and initializes it from details in the
   100         *  Server provided.
   101         *
   102         *  An Engine instance created this way has all the codecs that exist
   103         *  in the Server executable - with codec names matching the names
   104         *  configured into the Server, and is configured to use an appropriate
   105         *  memory map and other DSP-specific info.
   106         *
   107         *  Example usage:
   108         *  @p(code)
   109         *  var myEngine = Engine.createFromServer("video_copy",
   110         *                     "./video_copy.x64P",
   111         *                     "ti.sdo.ce.examples.servers.video_copy");
   112         *
   113         *  @param(engineName)        Name to be used for the engine created
   114         *  @param(serverExecutable)  Path to the server executable (including the
   115         *                            executable), relative from server package
   116         *  @param(serverPackage)     Name of the server package
   117         *
   118         *  @a(returns)               An Engine instance of the same type as
   119         *                            if {@link #create create()} were called.
   120         */
   121        function createFromServer(engineName, serverExecutable, serverPackage);
   122    
   123        /*!
   124         *  ======== close ========
   125         *  Internal close method (see package.xs)
   126         * @_nodoc
   127         */
   128        function close();
   129    
   130        /*!
   131         *  ======== validate ========
   132         *  Internal validate method (see package.xs)
   133         * @_nodoc
   134         */
   135        function validate();
   136    
   137        /*!
   138         * ======== usesIRES ========
   139         * Returns true if there is an engine with a local alg that implements
   140         * iresFxns. This function is used to determine whether or not RMAN
   141         * library needs to be linked in.
   142         *
   143         * @_nodoc
   144         */
   145        bool usesIRES();
   146    
   147        /*!
   148         *  ======== hasServer ========
   149         *  Returns true if there is an engine with a remote alg, or an engine
   150         *  that uses a server.
   151         *
   152         *  @_nodoc
   153         */
   154        bool hasServer();
   155    
   156    instance:
   157    
   158        /*!
   159         *  ======== create ========
   160         *  Create Engine instance
   161         *
   162         *  Parameters:
   163         *  @p(dlist)
   164         *      - `name`
   165         *          Name of this engine; this name is used by clients via the
   166         *          `Engine_open()` API to identify the collection of algorithms
   167         *          available.
   168         *
   169         *      - `algs`
   170         *          Array of algorithms this engine supports
   171         *
   172         *      - `server`
   173         *          Optional name of the DSP Server; this name is used (if
   174         *          necessary) to load and start any associated DSP CPUs required
   175         *          to support this Engine instance
   176         */
   177        create(String name, AlgDesc algs[]);
   178    
   179        /*!
   180         *  ======== name ========
   181         *  Name of the Engine
   182         *
   183         *  This string provided by the application in the `Engine_open()` call.
   184         */
   185        config String name;
   186    
   187        /*!
   188         *  ======== algs ========
   189         *  Array of algorithms available in the Engine
   190         *
   191         *  An array of algorithms which this Engine instance provides.  A mix
   192         *  of local and remote algorithms can be specified in this array.
   193         *
   194         *  {@link #createFromServer createFromServer()} can be used to populate
   195         *  this array with algorithms configured into a remote Server.
   196         *
   197         *  @see createFromServer
   198         */
   199        config AlgDesc algs[];
   200    
   201        /*!
   202         *  ======== server ========
   203         *  Optional name of a remote Server
   204         *
   205         *  This parameter is only necessary when there are algorithms configured
   206         *  to run remotely - i.e., their `local` field is set to false.
   207         *
   208         *  Engines containing these remote algorithms will need to set
   209         *  this `server` parameter to the name of the binary which should
   210         *  be loaded on the remote processor.
   211         */
   212        config String server;
   213    
   214        /*!
   215         *  ======== heapId ========
   216         *  Optional heap id to be used for this Engine
   217         *
   218         *  This is used internally, for example, by Comm_alloc().
   219         */
   220        config UInt32 heapId;
   221    
   222       /*!
   223         *  ======== useExtLoader ========
   224         *  In the case where the Engine has a remote server, @c useExtLoader
   225         *  specifies whether or not an external loader is used to load the
   226         *  server.
   227         *  If @c useExtLoader is set to false, Codec Engine will load the
   228         *  server when the Engine is opened.  Otherwise, it will be assumed
   229         *  that the server has already been loaded.
   230         */
   231        config Bool useExtLoader = false;
   232    
   233       /*!
   234         *  ======== memMap ========
   235         *  Optional name of file containing slave processor's memory map.
   236         *
   237         *  This parameter is only needed when Codec Engine will be loading
   238         *  the slave processor.
   239         */
   240        config String memMap;
   241    }
   242    /*
   243     *  @(#) ti.sdo.ce; 1, 0, 6,1; 8-14-2012 12:59:44; /db/atree/library/trees/ce/ce-u07/src/ xlibrary
   244    
   245     */
   246