Logging

Name

SIM_LOG_INFO… — output log message

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_log_info(int level, conf_object_t *NOTNULL dev, int grp,
             const char *NOTNULL fmt, ...);

void
SIM_log_spec_violation(int level, conf_object_t *NOTNULL dev, int grp,
                       const char *NOTNULL fmt, ...);

void
SIM_log_unimplemented(int level, conf_object_t *NOTNULL dev, int grp,
                      const char *NOTNULL fmt, ...);

void
SIM_log_error(conf_object_t *NOTNULL dev, int grp,
              const char *NOTNULL fmt, ...);

void
SIM_log_critical(conf_object_t *NOTNULL dev, int grp,
                 const char *NOTNULL fmt, ...);

void
SIM_log_message(conf_object_t *obj, int level, uint64 group_ids,
                log_type_t log_type, const char *message);

void
SIM_log_message_vararg(conf_object_t *NOTNULL obj, int level, uint64 grp,
                       log_type_t log_type, const char *NOTNULL fmt, ...);

// not available in DML

SIM_LOG_ERROR(dev, grp, ...);
SIM_LOG_CRITICAL(dev, grp, ...);
SIM_LOG_INFO(lvl, dev, grp, ...);
SIM_LOG_SPEC_VIOLATION(lvl, dev, grp, ...);
SIM_LOG_UNIMPLEMENTED(lvl, dev, grp, ...);
SIM_LOG_WARNING(dev, grp, ...);
SIM_LOG_INFO_ONCE(lvl1, lvl2, dev, grp, ...);
SIM_LOG_SPEC_VIOLATION_ONCE(lvl1, lvl2, dev, grp, ...);
SIM_LOG_UNIMPLEMENTED_ONCE(lvl1, lvl2, dev, grp, ...);
SIM_LOG_WARNING_ONCE(dev, grp, ...);

Python

import simics

simics.SIM_log_info(...)
simics.SIM_log_spec_violation(...)
simics.SIM_log_unimplemented(...)
simics.SIM_log_error(...)
simics.SIM_log_critical(...)
simics.SIM_log_message(...)

Description

These logging macros are used to emit information and error messages.

The level parameter indicates the importance; a lower value means a more important message. SIM_LOG_ERROR has no level parameter and will always emit messages.

level should be between 1 and 4:

1. important messages that are always printed
2. “high-level” informative messages
3. standard debug messages
4. detailed information, such as register accesses

The dev argument identifies the object the log message is about. The message is emitted for that object, so the object’s current log settings are used when the message is filtered and timestamped, and the object’s name is what appears in the formatted log message. In other words, pass the object whose behavior or state the message describes, not just the object making the call.

The grp parameter should have a bit set for each log group that the message corresponds to, as defined by the SIM_log_register_groups function, while a value of 0 equals any group.

The level and grp parameters allow the user to selectively display more or fewer messages using the log-level, log-group and log-type commands.

The fmt argument and those following it are used for string formatting in the same way as in the standard sprintf function.

The logging macros are among the few Simics APIs that may be called while a frontend exception is pending.

The use of the different macors is discussed in Simics Model Builder User’s Guide, section “Logging”:

• info: Normal informational message
• warning: Unexpected problem in the model, but simulation can continue.
• error: Unexpected error in the model (indicates a bug in the model).
• critical: Critical error that will interrupt the simulation (indicates a bug that the model may not recover from).
• spec_violation: Target program violates the specification.
• unimplemented: Attempt to use not yet implemented functionality.

If the sim->stop_on_error attribute is set to true, for example if Simics was started with the --stop-on-error command line flag, then Simics will exit with an error code when a log message of the error type is generated.

If the sim->warnings_as_errors attribute is set to true, for example if Simics was started with the --warnings-as-errors command line flag, then a log warning has the same effect as a log error.

From Python use the logging functions instead of the logging macros.

Execution Context

All contexts (including Threaded Context)

See Also

SIM_log_register_groups, SIM_attribute_error

Name

SIM_log_level, SIM_set_log_level — set and get log level

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

unsigned
SIM_log_level(const conf_object_t *NOTNULL obj);

void
SIM_set_log_level(conf_object_t *NOTNULL obj, unsigned level);

Python

import simics

simics.SIM_log_level(...)
simics.SIM_set_log_level(...)

Description

Retrieve or set the log level of an object. The level must be in the range 0..4 inclusive. Higher values mean more detailed logging.

Execution Context

Cell Context

Name

SIM_log_register_groups — register names of log groups

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_log_register_groups(conf_class_t *NOTNULL cls,
                        const char *const *NOTNULL names);

Python

import simics

simics.SIM_log_register_groups(...)

Description

Register a list of log groups that an object can use to separate messages. The order of the groups in the list defines the group ids that should be used in calls to SIM_LOG_INFO and similar functions. The group_ids argument to those functions should have a bit set corresponding to the group; i.e., a value of 1 for the first group, 2 for the second, 4 for the third, etc. names should be a NULL-terminated array.

A class may have up to 63 user-defined log groups.

The Default_Log_Group group is present on all classes. It is used for log entries where no group is specified.

Exceptions

SimExc_General Thrown in case of an error, e.g. if log groups are already registered.

Execution Context

Global Context

See Also

SIM_LOG_INFO