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        /*!
   125         *  ======== getDspMemTableFromServer ========
   126         *  Get a remote processor's memory table from a Server package
   127         *
   128         *  Given a Server package and an executable in that package, this method
   129         *  returns an object that contains the Server's memory map details.
   130         *
   131         *  For example:
   132         *  @p(code)
   133         *  myEngine.armDspLinkConfig.memTable =
   134         *      Engine.getDspMemTableFromServer(
   135         *                     "./video_copy.x64P",
   136         *                     "ti.sdo.ce.examples.servers.video_copy" );
   137         *
   138         *  @p
   139         *  There is no need to use this method when the preferred
   140         *  {@link #createFromServer createFromServer()} method is used first.
   141         *
   142         *  @param(serverExecutable)  Path to the server executable (including the
   143         *                            executable), relative from server package
   144         *  @param(serverPackage)     Name of the server package
   145         *
   146         *  @a(returns)               A DSP memory table "map" object, of type
   147         *                            ti.sdo.ce.osal.Global.
   148         *                            ArmDspLinkConfigMemTableEntry[string]
   149         *
   150         *  @see createFromServer
   151         */
   152        function getDspMemTableFromServer(serverExecutable, serverPackage);
   153    
   154        /*!
   155         *  ======== close ========
   156         *  Internal close method (see package.xs)
   157         * @_nodoc
   158         */
   159        function close();
   160    
   161        /*!
   162         *  ======== validate ========
   163         *  Internal validate method (see package.xs)
   164         * @_nodoc
   165         */
   166        function validate();
   167    
   168        /*!
   169         * ======== usesIDMA3 ========
   170         * Returns true if there is an engine with a local alg that implements
   171         * idma3Fxns. This function is used to determine whether or not DMAN3
   172         * library needs to be linked in.
   173         *
   174         * @_nodoc
   175         */
   176        bool usesIDMA3();
   177    
   178        /*!
   179         * ======== usesIRES ========
   180         * Returns true if there is an engine with a local alg that implements
   181         * iresFxns. This function is used to determine whether or not RMAN
   182         * library needs to be linked in.
   183         *
   184         * @_nodoc
   185         */
   186        bool usesIRES();
   187    
   188        /*!
   189         *  ======== hasServer ========
   190         *  Returns true if there is an engine with a remote alg, or an engine
   191         *  that uses a server.
   192         *
   193         *  @_nodoc
   194         */
   195        bool hasServer();
   196    
   197    instance:
   198    
   199        /*!
   200         *  ======== create ========
   201         *  Create Engine instance
   202         *
   203         *  Parameters:
   204         *  @p(dlist)
   205         *      - `name`
   206         *          Name of this engine; this name is used by clients via the
   207         *          `Engine_open()` API to identify the collection of algorithms
   208         *          available.
   209         *
   210         *      - `algs`
   211         *          Array of algorithms this engine supports
   212         *
   213         *      - `server`
   214         *          Optional name of the DSP Server; this name is used (if
   215         *          necessary) to load and start any associated DSP CPUs required
   216         *          to support this Engine instance
   217         */
   218        create(String name, AlgDesc algs[]);
   219    
   220        /*!
   221         *  ======== name ========
   222         *  Name of the Engine
   223         *
   224         *  This string provided by the application in the `Engine_open()` call.
   225         */
   226        config String name;
   227    
   228        /*!
   229         *  ======== algs ========
   230         *  Array of algorithms available in the Engine
   231         *
   232         *  An array of algorithms which this Engine instance provides.  A mix
   233         *  of local and remote algorithms can be specified in this array.
   234         *
   235         *  {@link #createFromServer createFromServer()} can be used to populate
   236         *  this array with algorithms configured into a remote Server.
   237         *
   238         *  @see createFromServer
   239         */
   240        config AlgDesc algs[];
   241    
   242        /*!
   243         *  ======== server ========
   244         *  Optional name of a remote Server
   245         *
   246         *  This parameter is only necessary when there are algorithms configured
   247         *  to run remotely - i.e., their `local` field is set to false.
   248         *
   249         *  Engines containing these remote algorithms will need to set
   250         *  this `server` parameter to the name of the binary which should
   251         *  be loaded on the remote processor.
   252         */
   253        config String server;
   254    
   255        /*!
   256         *  ======== heapId ========
   257         *  Optional heap id to be used for this Engine
   258         *
   259         *  This is used internally, for example, by Comm_alloc().
   260         */
   261        config UInt32 heapId;
   262    
   263        /*!
   264         *  ======== armDspLinkConfig ========
   265         *  Optional GPP-side Link configuration
   266         *
   267         *  The ARM-side DSP Link configuration.  If left undefined will revert to
   268         *  ti.sdo.ce.ipc.DEFAULT_ARMDSPLINKCONFIG, but with a warning
   269         *
   270         *  Applies only to CE configurations where
   271         *  osal.Global.runtimeEnv == DSPLINK_LINUX
   272         *
   273         *  @p
   274         *  There is no need to use this method when the preferred
   275         *  {@link #createFromServer createFromServer()} method is used first.
   276         *
   277         *  @see createFromServer
   278         */
   279        config ti.sdo.ce.ipc.IIpc.ArmDspLinkConfig armDspLinkConfig;
   280    
   281       /*!
   282         *  ======== useExtLoader ========
   283         *  In the case where the Engine has a remote server, @c useExtLoader
   284         *  specifies whether or not an external loader is used to load the
   285         *  server.
   286         *  If @c useExtLoader is set to false, Codec Engine will load the
   287         *  server when the Engine is opened.  Otherwise, it will be assumed
   288         *  that the server has already been loaded.
   289         */
   290        config Bool useExtLoader = false;
   291    
   292       /*!
   293         *  ======== memMap ========
   294         *  Optional name of file containing slave processor's memory map.
   295         *
   296         *  This parameter is only needed when Codec Engine will be loading
   297         *  the slave processor.
   298         */
   299        config String memMap;
   300    }
   301    /*
   302     *  @(#) ti.sdo.ce; 1, 0, 6,1; 1-17-2012 23:09:32; /db/atree/library/trees/ce/ce-t03/src/ xlibrary
   303    
   304     */
   305