1 /*!
2 * ======== Warnings ========
3 * Conditional warnings manager
4 * @nodoc
5 * This module declares all warnings generated by the packages in the xdc.*
6 * name space. Each warning is identified with an ID, a positive integer
7 * number. A warning message allows conversion specifiers that can be replaced
8 * with actual strings at the time a warning message is generated.
9 * The purpose of IDs is to let users find warning documentation in this module
10 * and also to allow warnings to be disabled based on their IDs.
11 */
12 metaonly module Warnings {
13 typedef String StringArray[];
14
15 /*!
16 * ======== Warning ========
17 * Warning descriptor
18 *
19 * Warnings are defined as instances of this structure, and also that's
20 * how the warnings are kept internally.
21 */
22 struct Warning {
23 Int id;
24 String msg;
25 }
26
27 /*!
28 * ======== WarningParams ========
29 * Structure passed to $logWarning
30 *
31 * Currently, the only parameter assigned to a warning is an array of
32 * strings to replace conversion specifiers in `Warning`s. In the future,
33 * a caller can identify a module where the warning is defined, which will
34 * allow any package to introduce new warnings.
35 */
36 struct WarningParams {
37 Warning warning;
38 StringArray args;
39 }
40
41 /*!
42 * ======== LOGID ========
43 * Multiple Log events with the same ID
44 *
45 * If two Log events share a message, they are automatically assigned
46 * the same ID because IDs also serve as pointers to an array that holds
47 * a compact representation of message strings. To avoid duplication of
48 * strings, if a string already exists in the array, the ID of the
49 * existing copy is used.
50 *
51 * This warning can be useful for package producers who unintentionally
52 * declare two events with the same message, which could be combined
53 * into one common Log event.
54 */
55 const Warning LOGID = {
56 id: 4,
57 msg: "Two events with the same id: %s and %s share the msg: '%s'. You must reconfigure the message of one of these events to ensure its id will be unique."
58 };
59
60 /*!
61 * ======== disable ========
62 * Internal function that disables warnings
63 *
64 * @param(ids) array of IDs
65 */
66 Void disable(StringArray ids);
67
68 /*!
69 * ======== getMessage ========
70 * Internal function that creates an actual output message
71 *
72 * @param(prms) WarningParams structure passed by the warning
73 * generation code
74 */
75 String getMessage(WarningParams prms);
76 }
77 78 79
80