|
|
| |
|
|
|
Tracing and Logging
17.1 Overview
UDI environments are expected to provide facilities for drivers to record information about their operation. There are two such types of information: log data, which describes infrequent events read by a system administrator to determine the state of a running system, and trace data, which is divided into classes of information used by developers and systems analysts for debugging UDI modules or the UDI subsystem as a whole. A driver is required to provide log data; providing trace data is optional.
This chapter defines the tracing and logging service calls which are provided for use by the driver to record both trace data and log data. Additional operations to specify the level of tracing generated are defined in the Management Metalanguage (see "Tracing Control Operations").
17.2 Tracing and Logging Service Calls
17.2.1 Tracing Calls
Tracing is initially disabled when a driver instance is initialized. The Management Metalanguage includes a channel operation to enable or disable tracing of specified types of events in a driver instance (see Section 24.4.1, "Tracing Control Operations"). Depending on the issue being debugged, the driver may be asked to trace only rare errors, all internal function calls, or somewhere in between. The actual set of events traced is up to the discretion of the driver implementation, but must in all cases be a subset of the currently enabled set of trace event types. Note that the environment may be filtering final trace output by some other criteria, even though the driver itself filters only by trace event type.
When the driver encounters an event to be traced, it calls udi_trace_write, passing the trace event code, a data buffer, and a pointer to its udi_init_context_t structure (identifying this driver region as the source of the data). The contents and format of trace data are driver implementation-dependent.
17.2.2 Logging Calls
Major events, including any situation where a udi_status_t value other than UDI_OK that indicates an exceptional condition is generated, should be logged by UDI drivers using udi_log_write. Logging is always active; it is not controlled by event masks as tracing is (though udi_log_write may be used to simultaneously log and trace data). As with tracing, however, the environment may choose to filter final log output on its own.
Although drivers can function without logging any data, making calls to udi_log_write when appropriate should not be considered optional. Such logging is particularly important because udi_log_write tags udi_status_t values with a correlation code (see Section 9.9.1, "UDI Status"), allowing it to associate related errors as they are passed from driver to driver.
17.2.3 Trace Event Types
Trace events specify the types of trace data which the driver is to report at any given time. Setting the corresponding bit value in the trace_event_mask mask in a udi_usage_ind operation (see Section 24.4.1) enables tracing for all events of a particular type. Some event types are designed to trace metalanguage-specific information or operations and are thus selectable on a per-metalanguage basis; these are referred to as metalanguage-selectable trace event types.
The trace events are divided into four different classes as defined in this section:
- common trace event codes, which apply to all drivers and metalanguages.
- common metalanguage-selectable trace event codes, whose semantics are defined in each metalanguage. The general semantics of the common metalanguage-selectable events are defined in this chapter; metalanguages can define more specific semantics as they conform to the general semantics defined here.
- metalanguage-specific trace event codes (UDI_TREVENT_META_SPECIFIC_n), with semantics defined by each metalanguage, are also metalanguage-selectable.
- driver-specific trace event codes (UDI_TREVENT_INTERNAL_n), which are available for tracing events specific to a single driver implementation.
Note that drivers and metalanguages can define the use of the driver or metalanguage-selectable event codes, respectively, without having to worry about event code usage defined by other drivers or metalanguages, since each trace call is associated with a particular calling driver and a selected metalanguage.
Note - Environment implementations may trace other types of events transparently to the driver, such as incoming and outgoing channel operations and service calls.
NAME udi_trevent_t
Trace event type definition
#include <udi.h>typedef udi_ubit32_t udi_trevent_t; /* Common Trace Events */#define UDI_TREVENT_LOCAL_PROC_ENTRY (1U<<0) #define UDI_TREVENT_LOCAL_PROC_EXIT (1U<<1) #define UDI_TREVENT_EXTERNAL_ERROR (1U<<2)/* Common Metalanguage-Selectable Trace Events */#define UDI_TREVENT_IO_SCHEDULED (1U<<6) #define UDI_TREVENT_IO_COMPLETED (1U<<7)/* Metalanguage-Specific Trace Events */#define UDI_TREVENT_META_SPECIFIC_1 (1U<<11) #define UDI_TREVENT_META_SPECIFIC_2 (1U<<12) #define UDI_TREVENT_META_SPECIFIC_3 (1U<<13) #define UDI_TREVENT_META_SPECIFIC_4 (1U<<14) #define UDI_TREVENT_META_SPECIFIC_5 (1U<<15)/* Driver-Specific Trace Events */#define UDI_TREVENT_INTERNAL_1 (1U<<16) #define UDI_TREVENT_INTERNAL_2 (1U<<17) #define UDI_TREVENT_INTERNAL_3 (1U<<18) #define UDI_TREVENT_INTERNAL_4 (1U<<19) #define UDI_TREVENT_INTERNAL_5 (1U<<20) #define UDI_TREVENT_INTERNAL_6 (1U<<21) #define UDI_TREVENT_INTERNAL_7 (1U<<22) #define UDI_TREVENT_INTERNAL_8 (1U<<23) #define UDI_TREVENT_INTERNAL_9 (1U<<24) #define UDI_TREVENT_INTERNAL_10 (1U<<25) #define UDI_TREVENT_INTERNAL_11 (1U<<26) #define UDI_TREVENT_INTERNAL_12 (1U<<27) #define UDI_TREVENT_INTERNAL_13 (1U<<28) #define UDI_TREVENT_INTERNAL_14 (1U<<29) #define UDI_TREVENT_INTERNAL_15 (1U<<30)/* Logging Event */#define UDI_TREVENT_LOG (1U<<31)DESCRIPTION The udi_trevent_t type definition is used to specify a bitmask of trace events. These trace events are used in the tracing and logging service calls to specify the occurrence of events or to provide masks to filter the set of interesting trace events.
The following common trace event codes are defined independently of any metalanguage.
UDI_TREVENT_LOCAL_PROC_ENTRY - Trace entry to all procedures that are local to the driver. Include argument values in the trace output.
UDI_TREVENT_LOCAL_PROC_EXIT - Trace exit from all procedures that are local to the driver. Include return values in the trace output.
UDI_TREVENT_EXTERNAL_ERROR - Trace error conditions that are passed from this driver to other UDI drivers or modules. This happens when a udi_status_t value other than UDI_OK that indicates an exceptional condition is generated. Such events must be logged using udi_log_write (which will handle the tracing of this event as well).
The following trace event types are designed to trace metalanguage-specific information or operations, and can therefore be selectively enabled and disabled on a per-metalanguage basis. For these events, tracing is enabled or disabled only for the metalanguages indicated by meta_idx of the trace usage operation (see "Tracing Control Operations"). Each metalanguage defines its own rules and conventions for the use of these event types; therefore, the metalanguage specifications should be consulted before using these events.
UDI_TREVENT_IO_SCHEDULED - Trace the point at which the driver starts handling a specific I/O request. The use of this trace point is different for different types of drivers but should indicate the point at which the driver passes the I/O request to the hardware. (Example: submission of a SCSI command to the hardware to be sent on the SCSI bus.) This trace event applies only to the responder role of a request/response metalanguage (e.g. GIO provider).
UDI_TREVENT_IO_COMPLETED - Trace the point at which an I/O request has been completed. This is the counterpart to UDI_TREVENT_IO_SCHEDULED and in a similar fashion the use of this trace event is determined by type of UDI driver. (Example: Interrupt indicating SCSI command complete.) This trace event applies only to the responder role of a request/response metalanguage (e.g. GIO provider).
UDI_TREVENT_META_SPECIFIC_n - Trace metalanguage-specific events as defined in each metalanguage.
The driver-internal trace events, UDI_TREVENT_INTERNAL_n, may be used to trace any driver-specific events desired. The interpretation of those events is determined by the driver implementor.
The logging event code is a special trace event code which is used to indicate that a logging event has occurred rather than one of the customary trace events. Logging events cannot be filtered.
UDI_TREVENT_LOG - Event code that is used for logging messages that are not associated with trace events. This event code must only be used with udi_log_write and not with udi_trace_write.
NAME udi_trace_write
Record trace data
#include <udi.h>void udi_trace_write ( udi_init_context_t *init_context, udi_trevent_t trace_event, udi_index_t meta_idx, udi_ubit32_t msgnum, ... );ARGUMENTS init_context is a pointer to the front of the driver's region data area and is used to uniquely identify this driver instance.
trace_event is the type of trace event being reported.
meta_idx is a metalanguage index number that identifies the metalanguage to which trace_event is relative, for metalanguage-selectable trace events. It must match the value of <meta_idx> in the corresponding "child_meta", "parent_meta", or "internal_meta" declaration of the driver's Static Driver Properties (see Chapter 30), or 0 for the Management Metalanguage. If the event is not metalanguage-selectable, meta_idx is ignored.
msgnum is the index value of a message string provided in the driver's static properties file (see Section 30.4.9, "Message Declaration"). This selects the text of the message to be traced. Any embedded formatting codes in the text of that message will be used to format the traced message with the remaining arguments supplied to this call. The formatting is performed as if the message string and remaining arguments were passed to the udi_snprintf utility function (see udi_snprintf).
... are the remaining arguments which provide the values used for the formatting codes contained in the message identified by msgnum. Arguments formatted with %c or %s format codes must not contain newline (`\n') or other control characters.
DESCRIPTION This routine traces data generated by the driver. Time-stamping of trace entries will be done at the discretion of the environment; the driver is not expected to supply timestamp information.
To simplify usage, udi_trace_write does not involve a callback. The environment will immediately copy the msgnum and remaining arguments into its own buffers for immediate or delayed processing. This may result in loss of trace data during unusually heavy usage. The driver writer is encouraged to keep trace entries short to minimize this possibility.
If the driver wishes to log and trace the same event, the udi_log_write operation should be used instead.
NAME udi_log_write
Record log data
#include <udi.h>void udi_log_write ( udi_log_write_call_t *callback, udi_cb_t *gcb, udi_trevent_t trace_event, udi_ubit8_t severity, udi_index_t meta_idx, udi_status_t original_status, udi_ubit32_t msgnum, ... ); typedef void udi_log_write_call_t ( udi_cb_t *gcb, udi_status_t correlated_status ); /* Values for severity */#define UDI_LOG_DISASTER 1 #define UDI_LOG_ERROR 2 #define UDI_LOG_WARNING 3 #define UDI_LOG_INFORMATION 4ARGUMENTS callback, gcb are standard arguments described in the "Asynchronous Service Calls" section of "Calling Sequence and Naming Conventions". Note that no init context pointer is required (unlike with udi_trace_write), since region identity is established through the gcb.
trace_event is the type of trace event to be logged. For log data that is not associated with trace events, use UDI_TREVENT_LOG.
severity specifies the severity level of the log data.
meta_idx is a metalanguage index number that identifies the metalanguage to which trace_event is relative, for metalanguage-selectable trace events. It must match the value of <meta_idx> in the corresponding "child_meta", "parent_meta", or "internal_meta" declaration of the driver's Static Driver Properties (see Chapter 30), or 0 for the Management Metalanguage. If the event is not metalanguage-selectable, meta_idx is ignored.
original_status is the UDI status value, if any, that was either generated by the driver or received from another driver. The environment will generate appropriate information in the log file for this status value; the driver may provided supplemental information with the msgnum and associated arguments.
msgnum is the index value of a message string provided in the driver's static properties file (see Section 30.4.9, "Message Declaration"). This selects the text of the message to be logged. Any embedded formatting codes in the text of that message will be used to format the traced message with the remaining arguments supplied to this call. The formatting is performed as if the message string and remaining arguments were passed to the udi_snprintf utility function (see udi_snprintf).
... are the remaining arguments which provide the values used for the formatting codes contained in the message identified by msgnum. Arguments formatted with %c or %s format codes must not contain newline (`\n') or other control characters.
correlated_status is the original_status value, possibly modified to include a new correlation value. (See the Fundamental Types Chapter for more information on the correlation field of the udi_status_t type.) The correlation value allows multiple log entries related to a single event to be correlated based on the correlation value assigned; if there is already a correlation value in the status code the udi_log_write call will preserve that original correlation.
WARNINGS Control block usage must follow the rules described in the "Asynchronous Service Calls" section of "Calling Sequence and Naming Conventions".
DESCRIPTION This routine logs events that can affect functionality of the driver, controlled hardware or other subsystems using the driver. Each of the data records may be automatically time stamped by the environment; the driver is not expected to supply timestamp information.
The following severity levels are defined:
UDI_LOG_DISASTER This severity indicates that the driver detected a severe and unrecoverable error condition that will likely affect multiple users of a driver and may jeopardize system integrity. Environments may take actions that result in killing the driver or the system upon logging this severity.
UDI_LOG_ERROR This severity indicates that the driver encountered an error condition that might cause some error conditions in its users, but from which it was able to recover.
UDI_LOG_WARNING This severity indicates minor abnormal conditions, likely caused by other subsystems.
UDI_LOG_INFORMATION This severity is used for expected events such as driver start-up or shutdown.
If the trace_event is not UDI_TREVENT_LOG, an implicit call to udi_trace_write will be made if tracing for the corresponding event type is enabled.
udi_log_write allows the environment to associate related events in different drivers with each other. It can do this by modifying the status codes it is passed to include a correlation value. This allows errors related to the same event to be correlated.
| |
|
|
|