1 /*
2 * Copyright (c) 2012 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 * ======== LoggerCallback.xdc ========
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, plugs in the user defined functions, assign it as
24 * the default logger for all modules, and enable `USER1` logging in all
25 * all 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 * ======== CreateInstFxn ========
61 * Logger instance create callback function signature
62 *
63 * `{@link LoggerCallback#arg} is passed as an argument to this function.
64 * The return value from this function will be passed as an argument
65 * to the `outputFxn`. In case of multiple LoggerCallback instances, the
66 * return value can be used in `outputFxn` to differentiate among the
67 * instances.
68 */
69 typedef UArg (*CreateInstFxn)(UArg);
70
71 /*!
72 * ======== outputFxn ========
73 * User supplied character callback function
74 *
75 * This function is called when the `Log` module needs to output an event.
76 * e.g. `{@link Log#write4()}` or `{@link Log#print2()}`
77 *
78 * By default, this function is configured with a default output function.
79 * The default function does nothing and returns.
80 */
81 config OutputFxn outputFxn = "&xdc_runtime_LoggerCallback_defaultOutput";
82
83 /*!
84 * ======== createInstFxn ========
85 * User supplied logger instance create function
86 *
87 * This function is called when the `{@link LoggerCallback#create}` is
88 * called.
89 *
90 * By default, this function is configured with a default create function.
91 * The default create function returns `0` always.
92 */
93 config CreateInstFxn createInstFxn = "&xdc_runtime_LoggerCallback_defaultCreate";
94
95 instance:
96
97 /*!
98 * ======== create ========
99 * Create a `LoggerCallback` logger instance
100 */
101 create();
102
103 /*!
104 * ======== arg ========
105 * User supplied argument for the user supplied create function.
106 *
107 * This user supplied argument will be passed back as an argument to the
108 * `createInstFxn` function. It can be used by the
109 * `{@link LoggerCallback#createInstFxn}` function at runtime to
110 * differentiate between the multiple logger instances configured in the
111 * user config script.
112 *
113 * The user can skip configuring this argument. In such a case, the
114 * default value `0` will be passed back as an argument to the
115 * `createInstFxn` function.
116 */
117 config UArg arg = 0;
118
119 internal:
120
121 struct Instance_State {
122 Bool enabled; /* Logger state */
123 UArg context; /* Logger instance */
124 UArg arg; /* Logger instance create argument */
125 };
126 }
127 /*
128 * @(#) xdc.runtime; 2, 1, 0,384; 9-3-2012 16:22:19; /db/ztree/library/trees/xdc/xdc-y35x/src/packages/
129 */
130