1 2 3 4 5 6 7 8 9 10 11 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(¶ms);
37 * params.instance->name = "myInstance";
38 * ModA_create(¶ms, 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(¶ms);
75 * params.instance->name = "myInstance";
76 * Mod_create(¶ms, 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 89
90