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 @RomConsts
44
45 module LoggerCallback inherits ILogger {
46
47 /*!
48 * ======== OutputFxn ========
49 * Character output callback function signature
50 *
51 * The first argument is the parameter returned by the call to
52 * `createInstFxn`.
53 * The second argument is a pointer to `{@link Log#EventRec}` record.
54 * The third argument is the number of arguments in`{@link Log#EventRec}`
55 *
56 * Note: Only evt and arg fields in `Log_EventRec` record are filled and
57 * passed to the user supplied function.
58 */
59 typedef Void (*OutputFxn)(UArg, Log.EventRec *, Int);
60
61 /*!
62 * ======== defaultOutput ========
63 * Default output function (always does nothing)
64 */
65 extern Void defaultOutput(UArg, Log.EventRec *, Int)
66 = xdc_runtime_LoggerCallback_defaultOutput;
67
68 /*!
69 * ======== CreateInstFxn ========
70 * Logger instance create callback function signature
71 *
72 * `{@link LoggerCallback#arg} is passed as an argument to this function.
73 * The return value from this function will be passed as an argument
74 * to the `outputFxn`. In case of multiple LoggerCallback instances, the
75 * return value can be used in `outputFxn` to differentiate among the
76 * instances.
77 */
78 typedef UArg (*CreateInstFxn)(UArg);
79
80 /*!
81 * ======== defaultCreate ========
82 * Default create function (always returns 0)
83 */
84 extern UArg defaultCreate(UArg) = xdc_runtime_LoggerCallback_defaultCreate;
85
86 /*!
87 * ======== outputFxn ========
88 * User supplied character callback function
89 *
90 * This function is called when the `Log` module needs to output an event.
91 * e.g. `{@link Log#write4()}` or `{@link Log#print2()}`
92 *
93 * By default, this function is configured with a default output function.
94 * The default function does nothing and returns.
95 */
96 config OutputFxn outputFxn = "&xdc_runtime_LoggerCallback_defaultOutput";
97
98 /*!
99 * ======== createInstFxn ========
100 * User supplied logger instance create function
101 *
102 * This function is called when the `{@link LoggerCallback#create}` is
103 * called.
104 *
105 * By default, this function is configured with a default create function.
106 * The default create function always returns `0`.
107 */
108 config CreateInstFxn createInstFxn = "&xdc_runtime_LoggerCallback_defaultCreate";
109
110 instance:
111
112 /*!
113 * ======== create ========
114 * Create a `LoggerCallback` logger instance
115 */
116 create();
117
118 /*!
119 * ======== arg ========
120 * User supplied argument for the user supplied create function.
121 *
122 * This user supplied argument will be passed back as an argument to the
123 * `createInstFxn` function. It can be used by the
124 * `{@link LoggerCallback#createInstFxn}` function at runtime to
125 * differentiate between the multiple logger instances configured in the
126 * user config script.
127 *
128 * The user can skip configuring this argument. In such a case, the
129 * default value `0` will be passed back as an argument to the
130 * `createInstFxn` function.
131 */
132 config UArg arg = 0;
133
134 internal:
135
136 struct Instance_State {
137 Bool enabled;
138 UArg context;
139 UArg arg;
140 };
141 }
142 143 144
145