1    /* 
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved. 
     3     *  This program and the accompanying materials are made available under the 
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at 
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*!
    14     *  ======== IInstance ========
    15     *  Common instance params
    16     *
    17     *  Every module's instance parameter structure contains a pointer to an
    18     *  `IInstance.Params` structure named `instance`.  So, every instance
    19     *  parameter defined in this interface may optionally be set when
    20     *  creating (or constructing) any module's instances.
    21     */
    22    interface IInstance {
    23    
    24    instance:
    25    
    26        /*! 
    27         *  ======== name ========
    28         *  Name of the instance
    29         *
    30         *  It is possible to "bind" a name to each instance of any module
    31         *  at the time the instance is created (or constructed).  
    32         *  @p(code)
    33         *      ModA_Params params;
    34         *      ModA_Params_init(&params);
    35         *      params.instance->name = "myInstance";
    36         *      ModA_create(&params, NULL);
    37         *  @p
    38         *
    39         *  The name field must be assigned a pointer to a buffer that persists
    40         *  as long as the instance that it names exists.  Only a reference to
    41         *  the name is retained in the instance, the name is not copied to a
    42         *  secondary buffer.
    43         *
    44         *  The configuration parameters that controls if instance names are
    45         *  supported is `common$.namedInstance`. The parameter is a member of the
    46         *  structure `{@link xdc.runtime.Types#Common$ common$}`, available in each
    47         *  module. By default, this parameter is set to `false`, which disables
    48         *  support for instance names.
    49         *  Therefore, to enable instance names for a given module `Mod`, configure
    50         *  the module as follows in your configuration script:
    51         *  @p(code)
    52         *      var Mod = xdc.useModule('pkg.Mod');
    53         *      ModA.common$.namedInstance = true;
    54         *  @p
    55         *
    56         *  Here is how the static instances are given names at the configuration
    57         *  time:
    58         *  @p(code)
    59         *      var inst = Mod.create();
    60         *      inst.instance.name = "myInstance";
    61         *  @p
    62         * 
    63         *  At runtime, assign your instance a name:
    64         *  @p(code)
    65         *      #include <package/name/Mod.h>
    66         *      Mod_Params params;
    67         *      Mod_Params_init(&params);
    68         *      params.instance->name = "myInstance";
    69         *      Mod_create(&params, NULL);
    70         *  @p
    71         *
    72         *  If instances have been configured to not support names, it is still
    73         *  possible to assign to the `instance.name` field of the parameter
    74         *  structure (as shown above).  However, the pointer is not retained
    75         *  and methods that normally return an instance's name will return
    76         *  `NULL` instead.
    77         */
    78        config String name = null;
    79    }
    80    /*
    81     *  @(#) xdc.runtime; 2, 1, 0,371; 2-10-2012 10:18:54; /db/ztree/library/trees/xdc/xdc-y21x/src/packages/
    82     */
    83