1    /* 
     2     * Copyright (c) 2010, 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         *  ======== noCommName ========
    58         *  Create a Comm which doesn't pollute the Comm namespace.
    59         *
    60         *  Some ipc implementations (not all!) support creating an unnamed
    61         *  Comm.  DSP Link is adding support for this, the WinCE port will have
    62         *  support before the Linux port.  To help bridge the gap until all
    63         *  Link ports have this feature, and so we continue to work with Link
    64         *  releases that don't have this feature, CE is temporarily introducing
    65         *  this `noCommName` boolean.
    66         *
    67         *  The default behavior is "as before", but for users that require
    68         *  unnamed Comm creates (e.g. kernel mode WinCE users), they can set
    69         *  this config param to `true` - on ipc ports that support it(!).
    70         *
    71         *  The intent is to remove this `noCommName config param as soon as
    72         *  all Link ports support it, so don't get attached to it!
    73         *
    74         *  @_nodoc
    75         */
    76        config Bool noCommName = false;
    77    
    78        /*!
    79         *  ======== AlgDesc ========
    80         *  Algorithm descriptor
    81         *
    82         *  Each engine "contains" multiple algorithms described by AlgDesc
    83         *  structures.
    84         *
    85         *  @field(name)    This string specifies the "local" name used by the
    86         *                  application to identify the algorithm to instantiate
    87         *  @field(mod)     This field is a module reference that identifies the
    88         *                  actual module implementing the algorithm to instantiate
    89         *  @field(local)   If true, the algorithm should be instantiated on the
    90         *                  "local" CPU; otherwise the server will create an
    91         *                  instance of the algorithm identifed by `mod`.
    92         *  @field(groupId) This id specifies which resource sharing group
    93         *                  this codec will be placed into.  This 'group' concept
    94         *                  is used by the framework to ensure algorithms in the
    95         *                  same group don't pre-empt each other and corrupt the
    96         *                  shared resources.
    97         *
    98         *                  Note that this parameter is ignored if `local` is not
    99         *                  TRUE.
   100         */
   101        struct AlgDesc {
   102            String          name;       /*! Alg nick-name */
   103            ICodec.Module   mod;        /*! The alg implementation */
   104            Bool            local;      /*! Run algorithm locally */
   105            Int             groupId;    /*! Alg group ID for sharing resources */
   106        };
   107    
   108        /*!
   109         *  ======== createFromServer ========
   110         *  Create an Engine from a Server package
   111         *
   112         *  Given a Server package and an executable in that package, this method
   113         *  creates an Engine instance and initializes it from details in the
   114         *  Server provided.
   115         *
   116         *  An Engine instance created this way has all the codecs that exist
   117         *  in the Server executable - with codec names matching the names
   118         *  configured into the Server, and is configured to use an appropriate
   119         *  memory map and other DSP-specific info.
   120         *
   121         *  Example usage:
   122         *  @p(code)
   123         *  var myEngine = Engine.createFromServer("video_copy",
   124         *                     "./video_copy.x64P",
   125         *                     "ti.sdo.ce.examples.servers.video_copy");
   126         *
   127         *  @param(engineName)        Name to be used for the engine created
   128         *  @param(serverExecutable)  Path to the server executable (including the
   129         *                            executable), relative from server package
   130         *  @param(serverPackage)     Name of the server package
   131         *
   132         *  @a(returns)               An Engine instance of the same type as
   133         *                            if {@link #create create()} were called.
   134         */
   135        function createFromServer(engineName, serverExecutable, serverPackage);
   136    
   137    
   138        /*!
   139         *  ======== getDspMemTableFromServer ========
   140         *  Get a remote processor's memory table from a Server package
   141         *
   142         *  Given a Server package and an executable in that package, this method
   143         *  returns an object that contains the Server's memory map details.
   144         *
   145         *  For example:
   146         *  @p(code)
   147         *  myEngine.armDspLinkConfig.memTable =
   148         *      Engine.getDspMemTableFromServer(
   149         *                     "./video_copy.x64P",
   150         *                     "ti.sdo.ce.examples.servers.video_copy" );
   151         *
   152         *  @p
   153         *  There is no need to use this method when the preferred
   154         *  {@link #createFromServer createFromServer()} method is used first.
   155         *
   156         *  @param(serverExecutable)  Path to the server executable (including the
   157         *                            executable), relative from server package
   158         *  @param(serverPackage)     Name of the server package
   159         *
   160         *  @a(returns)               A DSP memory table "map" object, of type
   161         *                            ti.sdo.ce.osal.Global.
   162         *                            ArmDspLinkConfigMemTableEntry[string]
   163         *
   164         *  @see createFromServer
   165         */
   166        function getDspMemTableFromServer(serverExecutable, serverPackage);
   167    
   168        /*!
   169         *  ======== close ========
   170         *  Internal close method (see package.xs)
   171         * @_nodoc
   172         */
   173        function close();
   174    
   175        /*!
   176         *  ======== validate ========
   177         *  Internal validate method (see package.xs)
   178         * @_nodoc
   179         */
   180        function validate();
   181    
   182        /*!
   183         * ======== usesIDMA3 ========
   184         * Returns true if there is an engine with a local alg that implements
   185         * idma3Fxns. This function is used to determine whether or not DMAN3
   186         * library needs to be linked in.
   187         *
   188         * @_nodoc
   189         */
   190        bool usesIDMA3();
   191    
   192        /*!
   193         * ======== usesIRES ========
   194         * Returns true if there is an engine with a local alg that implements
   195         * iresFxns. This function is used to determine whether or not RMAN
   196         * library needs to be linked in.
   197         *
   198         * @_nodoc
   199         */
   200        bool usesIRES();
   201    
   202        /*!
   203         *  ======== hasServer ========
   204         *  Returns true if there is an engine with a remote alg, or an engine
   205         *  that uses a server.
   206         *
   207         *  @_nodoc
   208         */
   209        bool hasServer();
   210    
   211    instance:
   212    
   213        /*!
   214         *  ======== create ========
   215         *  Create Engine instance
   216         *
   217         *  Parameters:
   218         *  @p(dlist)
   219         *      - `name`
   220         *          Name of this engine; this name is used by clients via the
   221         *          `Engine_open()` API to identify the collection of algorithms
   222         *          available.
   223         *
   224         *      - `algs`
   225         *          Array of algorithms this engine supports
   226         *
   227         *      - `server`
   228         *          Optional name of the DSP Server; this name is used (if
   229         *          necessary) to load and start any associated DSP CPUs required
   230         *          to support this Engine instance
   231         */
   232        create(String name, AlgDesc algs[]);
   233    
   234        /*!
   235         *  ======== name ========
   236         *  Name of this engine.
   237         *
   238         *  This string provided by the application in the `Engine_open()` call.
   239         */
   240        config String name;
   241    
   242        /*!
   243         *  ======== algs ========
   244         *  Array of algorithms available in an Engine
   245         *
   246         *  An array of algorithms which this Engine instance provides.  A mix
   247         *  of local and remote algorithms can be specified in this array.
   248         *
   249         *  {@link #createFromServer createFromServer()} can be used to populate
   250         *  this array with algorithms configured into a remote Server.
   251         *
   252         *  @see createFromServer
   253         */
   254        config AlgDesc algs[];
   255    
   256        /*!
   257         *  ======== server ========
   258         *  Optional name of the remote server.
   259         *
   260         *  This parameter is only necessary when there are algorithms configured
   261         *  to run remotely - i.e., their `local` field is set to false.
   262         *
   263         *  Engines containing these remote algorithms will need to set
   264         *  this `server` parameter to the name of the binary which should
   265         *  be loaded on the remote processor.
   266         */
   267        config String server;
   268    
   269        /*!
   270         *  ======== armDspLinkConfig ========
   271         *  ARM-side DSP Link configuration
   272         *
   273         *  The ARM-side DSP Link configuration.  If left undefined will revert to
   274         *  ti.sdo.ce.ipc.DEFAULT_ARMDSPLINKCONFIG, but with a warning
   275         *
   276         *  Applies only to CE configurations where
   277         *  osal.Global.runtimeEnv == DSPLINK_LINUX
   278         *
   279         *  @p
   280         *  There is no need to use this method when the preferred
   281         *  {@link #createFromServer createFromServer()} method is used first.
   282         *
   283         *  @see createFromServer
   284         */
   285        config ti.sdo.ce.ipc.IIpc.ArmDspLinkConfig armDspLinkConfig;
   286    
   287       /*!
   288         *  ======== linkCfg ========
   289         *  Optional name of DSP Link configuration.
   290         *
   291         *  This parameter is only needed when LAD is used to
   292         *  arbitrate control of the DSP server
   293         */
   294        config String linkCfg;
   295    }
   296    /*
   297     *  @(#) ti.sdo.ce; 1, 0, 6,432; 12-2-2010 21:19:07; /db/atree/library/trees/ce/ce-r11x/src/ xlibrary
   298    
   299     */
   300