1 2 3 4 5 6 7 8 9 10 11 12
13 14 15
16 package xdc.runtime;
17 /*!
18 * ======== LoggerCallback ========
19 * A logger that passes events to a user supplied callback function
20 *
21 * @a(Examples)
22 * Configuration example: The following XDC configuration statements
23 * create a logger instance, plug in the user defined functions, assign it as
24 * the default logger for all modules, and enable `USER1` logging in all
25 * modules of the package `my.pkg`. See the
26 * `{@link Diags#setMaskMeta Diags.setMaskMeta()}` function for details on
27 * specifying the module names.
28 *
29 * @p(code)
30 * var Defaults = xdc.useModule('xdc.runtime.Defaults');
31 * var Diags = xdc.useModule('xdc.runtime.Diags');
32 * var LoggerCallback = xdc.useModule('xdc.runtime.LoggerCallback');
33 * LoggerCallback.outputFxn = "&userOutputFunc";
34 * LoggerCallback.createInstFxn = "&userCreateInstFunc";
35 *
36 * var loggerParams = new Logger.Params();
37 * loggerParams.arg = 1;
38 * Defaults.common$.logger = LoggerCallback.create(loggerParams);
39 * Diags.setMaskMeta("my.pkg.%", Diags.USER1, Diags.RUNTIME_ON);
40 * @p
41 */
42 @ModuleStartup
43 module LoggerCallback inherits ILogger {
44
45 /*!
46 * ======== OutputFxn ========
47 * Character output callback function signature
48 *
49 * The first argument is the parameter returned by the call to
50 * `createInstFxn`.
51 * The second argument is a pointer to `{@link Log#EventRec}` record.
52 * The third argument is the number of arguments in`{@link Log#EventRec}`
53 *
54 * Note: Only evt and arg fields in `Log_EventRec` record are filled and
55 * passed to the user supplied function.
56 */
57 typedef Void (*OutputFxn)(UArg, Log.EventRec *, Int);
58
59 /*!
60 * ======== defaultOutput ========
61 * Default output function (always does nothing)
62 */
63 extern Void defaultOutput(UArg, Log.EventRec *, Int)
64 = xdc_runtime_LoggerCallback_defaultOutput;
65
66 /*!
67 * ======== CreateInstFxn ========
68 * Logger instance create callback function signature
69 *
70 * `{@link LoggerCallback#arg} is passed as an argument to this function.
71 * The return value from this function will be passed as an argument
72 * to the `outputFxn`. In case of multiple LoggerCallback instances, the
73 * return value can be used in `outputFxn` to differentiate among the
74 * instances.
75 */
76 typedef UArg (*CreateInstFxn)(UArg);
77
78 /*!
79 * ======== defaultCreate ========
80 * Default create function (always returns 0)
81 */
82 extern UArg defaultCreate(UArg) = xdc_runtime_LoggerCallback_defaultCreate;
83
84 /*!
85 * ======== outputFxn ========
86 * User supplied character callback function
87 *
88 * This function is called when the `Log` module needs to output an event.
89 * e.g. `{@link Log#write4()}` or `{@link Log#print2()}`
90 *
91 * By default, this function is configured with a default output function.
92 * The default function does nothing and returns.
93 */
94 config OutputFxn outputFxn = "&xdc_runtime_LoggerCallback_defaultOutput";
95
96 /*!
97 * ======== createInstFxn ========
98 * User supplied logger instance create function
99 *
100 * This function is called when the `{@link LoggerCallback#create}` is
101 * called.
102 *
103 * By default, this function is configured with a default create function.
104 * The default create function always returns `0`.
105 */
106 config CreateInstFxn createInstFxn = "&xdc_runtime_LoggerCallback_defaultCreate";
107
108 instance:
109
110 /*!
111 * ======== create ========
112 * Create a `LoggerCallback` logger instance
113 */
114 create();
115
116 /*!
117 * ======== arg ========
118 * User supplied argument for the user supplied create function.
119 *
120 * This user supplied argument will be passed back as an argument to the
121 * `createInstFxn` function. It can be used by the
122 * `{@link LoggerCallback#createInstFxn}` function at runtime to
123 * differentiate between the multiple logger instances configured in the
124 * user config script.
125 *
126 * The user can skip configuring this argument. In such a case, the
127 * default value `0` will be passed back as an argument to the
128 * `createInstFxn` function.
129 */
130 config UArg arg = 0;
131
132 internal:
133
134 struct Instance_State {
135 Bool enabled;
136 UArg context;
137 UArg arg;
138 };
139 }
140 141 142
143