blob: ba68a23d030f324b4bd437c3a2d87afda749da2e [file] [log] [blame]
* ======== Warnings ========
* Conditional warnings manager
* @nodoc
* This module declares all warnings generated by the packages in the xdc.*
* name space. Each warning is identified with an ID, a positive integer
* number. A warning message allows conversion specifiers that can be replaced
* with actual strings at the time a warning message is generated.
* The purpose of IDs is to let users find warning documentation in this module
* and also to allow warnings to be disabled based on their IDs.
metaonly module Warnings {
typedef String StringArray[];
* ======== Warning ========
* Warning descriptor
* Warnings are defined as instances of this structure, and also that's
* how the warnings are kept internally.
struct Warning {
Int id;
String msg;
* ======== WarningParams ========
* Structure passed to $logWarning
* Currently, the only parameter assigned to a warning is an array of
* strings to replace conversion specifiers in `Warning`s. In the future,
* a caller can identify a module where the warning is defined, which will
* allow any package to introduce new warnings.
struct WarningParams {
Warning warning;
StringArray args;
* ======== LOGID ========
* Multiple Log events with the same ID
* If two Log events share a message, they are automatically assigned
* the same ID because IDs also serve as pointers to an array that holds
* a compact representation of message strings. To avoid duplication of
* strings, if a string already exists in the array, the ID of the
* existing copy is used.
* This warning can be useful for package producers who unintentionally
* declare two events with the same message, which could be combined
* into one common Log event.
const Warning LOGID = {
id: 4,
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."
* ======== disable ========
* Internal function that disables warnings
* @param(ids) array of IDs
Void disable(StringArray ids);
* ======== getMessage ========
* Internal function that creates an actual output message
* @param(prms) WarningParams structure passed by the warning
* generation code
String getMessage(WarningParams prms);