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    @DirectCall
    23    
    24    interface IInstance {
    25    
    26    instance:
    27    
    28        /*!
    29         *  ======== name ========
    30         *  Name of the instance
    31         *
    32         *  It is possible to "bind" a name to each instance of any module
    33         *  at the time the instance is created (or constructed).
    34         *  @p(code)
    35         *      ModA_Params params;
    36         *      ModA_Params_init(&params);
    37         *      params.instance->name = "myInstance";
    38         *      ModA_create(&params, NULL);
    39         *  @p
    40         *
    41         *  The name field must be assigned a pointer to a buffer that persists
    42         *  as long as the instance that it names exists.  Only a reference to
    43         *  the name is retained in the instance, the name is not copied to a
    44         *  secondary buffer.
    45         *
    46         *  The configuration parameters that controls if instance names are
    47         *  supported is `common$.namedInstance`. The parameter is a member of the
    48         *  structure `{@link xdc.runtime.Types#Common$ common$}`, available in 
    49         *  each module. By default, this parameter is set to `false`, which 
    50         *  disables support for instance names.
    51         *  Therefore, to enable instance names for a given module `Mod`, configure
    52         *  the module as follows in your configuration script:
    53         *  @p(code)
    54         *      var Mod = xdc.useModule('pkg.Mod');
    55         *      ModA.common$.namedInstance = true;
    56         *  @p
    57         *
    58         *  Here is how the static instances are given names at the configuration
    59         *  time:
    60         *  @p(code)
    61         *      var inst = Mod.create();
    62         *      inst.instance.name = "myInstance";
    63         *  @p
    64         *
    65         *  If instance names are enabled and used for statically created
    66         *  instances, the config parameter
    67         *  `{@link xdc.runtime.Text#isLoaded Text.isLoaded}` must be set to
    68         *  `true` to have these names available at runtime.
    69         *
    70         *  At runtime, assign your instance a name:
    71         *  @p(code)
    72         *      #include <package/name/Mod.h>
    73         *      Mod_Params params;
    74         *      Mod_Params_init(&params);
    75         *      params.instance->name = "myInstance";
    76         *      Mod_create(&params, NULL);
    77         *  @p
    78         *
    79         *  If instances have been configured to not support names, it is still
    80         *  possible to assign to the `instance.name` field of the parameter
    81         *  structure (as shown above).  However, the pointer is not retained
    82         *  and methods that normally return an instance's name will return
    83         *  `NULL` instead.
    84         */
    85        config CString name = null;
    86    }
    87    /*
    88     *  @(#) xdc.runtime; 2, 1, 0,0; 2-8-2017 14:15:55; /db/ztree/library/trees/xdc/xdc-D05/src/packages/
    89     */
    90