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