613 lines
19 KiB
C
613 lines
19 KiB
C
/* **********************************************************
|
|
* Copyright 2007 - 2009 VMware, Inc. All rights reserved.
|
|
* **********************************************************/
|
|
|
|
/*
|
|
* @VMKAPIMOD_LICENSE@
|
|
*/
|
|
|
|
/*
|
|
***********************************************************************
|
|
* Logging */ /**
|
|
* \addtogroup Core
|
|
* @{
|
|
* \defgroup Logging Kernel Logging
|
|
*
|
|
* The logging interfaces provide a means of writing informational
|
|
* and error messages to the kernel's logs.
|
|
*
|
|
* @{
|
|
***********************************************************************
|
|
*/
|
|
|
|
#ifndef _VMKAPI_LOGGING_H_
|
|
#define _VMKAPI_LOGGING_H_
|
|
|
|
/** \cond never */
|
|
#ifndef VMK_HEADER_INCLUDED_FROM_VMKAPI_H
|
|
#error This vmkapi file should never be included directly but only via vmkapi.h
|
|
#endif
|
|
/** \endcond never */
|
|
|
|
#include <stdarg.h>
|
|
|
|
/** \brief Opaque log component handle. */
|
|
typedef struct vmk_LogComponentInt *vmk_LogComponent;
|
|
|
|
/** \brief Log handle guaranteed to be invalid. */
|
|
#define VMK_INVALID_LOG_HANDLE NULL
|
|
|
|
/** \brief Log urgency level. */
|
|
typedef enum {
|
|
VMK_LOG_URGENCY_DEBUG,
|
|
VMK_LOG_URGENCY_NORMAL,
|
|
VMK_LOG_URGENCY_WARNING,
|
|
VMK_LOG_URGENCY_ALERT
|
|
} vmk_LogUrgency ;
|
|
|
|
/** \brief Types of log throttling */
|
|
typedef enum {
|
|
/** Log is not throttled. All messages will be logged. */
|
|
VMK_LOG_THROTTLE_NONE=0,
|
|
|
|
/**
|
|
* An internal message count will be kept and messages will
|
|
* only be logged as the count reaches certain wider-spaced values.
|
|
*/
|
|
VMK_LOG_THROTTLE_COUNT=1,
|
|
|
|
/**
|
|
* Messages will be logged depending on the return value
|
|
* of a custom log throttling function.
|
|
*/
|
|
VMK_LOG_THROTTLE_CUSTOM=2,
|
|
} vmk_LogThrottleType;
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_LogThrottleFunc -- */ /**
|
|
*
|
|
* \brief Custom throttling function for a log component.
|
|
*
|
|
* \note This callback is not allowed to block.
|
|
*
|
|
* A log throttling function will be called each time an attempt to
|
|
* log a message to a log component is made. If this function returns
|
|
* VMK_TRUE, the message will be logged. Otherwise, the message will
|
|
* not be logged.
|
|
*
|
|
* \param[in] arg Private data argument
|
|
*
|
|
* \return Whether or not the logger should log the current log message.
|
|
* \retval VMK_TRUE Log the current message.
|
|
* \retval VMK_FALSE Do not log the current message.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
typedef vmk_Bool (*vmk_LogThrottleFunc)(void *arg);
|
|
|
|
/**
|
|
* \brief Properties that define the type of throttling for
|
|
* a particular log component.
|
|
*/
|
|
typedef struct vmk_LogThrottleProperties {
|
|
/** Type of log throttling to use. */
|
|
vmk_LogThrottleType type;
|
|
|
|
/** Properties for the specified log throttling type. */
|
|
union {
|
|
/** Properties for a custom log throttler. */
|
|
struct {
|
|
/**
|
|
* Throttling function to call on each message submitted to the
|
|
* log component.
|
|
*/
|
|
vmk_LogThrottleFunc throttler;
|
|
|
|
/**
|
|
* Private data argument to pass to the log throttling function
|
|
* on each call.
|
|
*/
|
|
void *arg;
|
|
} custom;
|
|
} info;
|
|
} vmk_LogThrottleProperties;
|
|
|
|
/**
|
|
* \brief Properties that define a logging component.
|
|
*/
|
|
typedef struct vmk_LogProperties {
|
|
/** Name of the log component. */
|
|
vmk_Name name;
|
|
/** Module that owns the logging component. */
|
|
vmk_ModuleID module;
|
|
/** Heap to allocate the component and any other tracking information. */
|
|
vmk_HeapID heap;
|
|
/** Default log level. */
|
|
vmk_int32 defaultLevel;
|
|
/**
|
|
* Throttling properties for the new component or NULL if no throttling
|
|
* is required.
|
|
*/
|
|
const vmk_LogThrottleProperties *throttle;
|
|
} vmk_LogProperties;
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_StatusToString -- */ /**
|
|
*
|
|
* \brief Convert a status into a human readable text string
|
|
*
|
|
* \note This function will not block.
|
|
*
|
|
* \note The strings returned from this function for a particular
|
|
* status can change across releases regardless of binary
|
|
* compatibility. Do not rely on specific string contents.
|
|
* These are only intended to be used for display in logging.
|
|
*
|
|
* \param[in] status Return status code to convert to a
|
|
* human-readable string.
|
|
*
|
|
* \return Human-readable string that describes the supplied status.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
const char *vmk_StatusToString(
|
|
VMK_ReturnStatus status);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_LogRegister -- */ /**
|
|
*
|
|
* \brief Register a log component
|
|
*
|
|
* \note This function will not block.
|
|
*
|
|
* \param[in] props Properties for the new logging component.
|
|
* \param[out] handle Handle to the newly created log component.
|
|
*
|
|
* \retval VMK_BAD_PARAM Bad LogThrottleType specified in
|
|
* the throttle properties.
|
|
* \retval VMK_NO_MEMORY Not enough memory on the heap or
|
|
* to create the new logging component.
|
|
* \retval VMK_INVALID_MODULE Supplied module ID is invalid.
|
|
* \retval VMK_EXISTS A log component with the same name has
|
|
* already been registered.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_LogRegister(
|
|
const vmk_LogProperties *props,
|
|
vmk_LogComponent *handle);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_LogUnregister -- */ /**
|
|
*
|
|
* \brief Unregister a log component
|
|
*
|
|
* \note This function will not block.
|
|
*
|
|
* Should be used to unregister an existing logging component
|
|
*
|
|
* \note Should be called before the module heap is destroyed.
|
|
*
|
|
* \param[in] handle Pointer to handle for log component to be
|
|
* unregistered.
|
|
*
|
|
* \retval VMK_NOT_FOUND Supplied log component is invalid/unregisterd.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_LogUnregister(
|
|
vmk_LogComponent handle);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_LogGetName -- */ /**
|
|
*
|
|
* \brief Get log component name as a printable string.
|
|
*
|
|
* \note This function will not block.
|
|
*
|
|
* \param[in] handle Log component handle.
|
|
*
|
|
* \return The name associated with the supplied log component handle
|
|
* as a printable string.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
const char * vmk_LogGetName(
|
|
vmk_LogComponent handle);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_LogGetCurrentLogLevel -- */ /**
|
|
*
|
|
* \brief Get current log level of the given component
|
|
*
|
|
* \note This function will not block.
|
|
*
|
|
* \param[in] handle Log component handle.
|
|
*
|
|
* \return Current log level of the given component returned.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
vmk_int32 vmk_LogGetCurrentLogLevel(
|
|
vmk_LogComponent handle);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_LogDebug -- */ /**
|
|
*
|
|
* \brief Log a message to a logging component on debug builds only.
|
|
*
|
|
* Should be used to log information messages and non-error conditions.
|
|
*
|
|
* Messages are logged only if the component's log level is greater
|
|
* than or equal to the minimum log level specified.
|
|
*
|
|
* \printformatstringdoc
|
|
* \note This function will not block.
|
|
*
|
|
* \param[in] handle Log component handle,
|
|
* \param[in] min Minimum log level required to print the message,
|
|
* \param[in] fmt Format string,
|
|
* \param[in] args List of message arguments,
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
#ifndef VMX86_LOG
|
|
#define vmk_LogDebug(handle, min, fmt, args...)
|
|
#else
|
|
#define vmk_LogDebug(handle, min, fmt, args...) \
|
|
vmk_LogLevel(VMK_LOG_URGENCY_DEBUG, handle, min, \
|
|
"%s: %s:%d: " fmt "\n", vmk_LogGetName(handle), \
|
|
__FUNCTION__, __LINE__, ##args)
|
|
#endif
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_Log -- */ /**
|
|
*
|
|
* \brief Log message to a logging component at its current log level.
|
|
*
|
|
* Should be used to log information messages and non-error conditions.
|
|
*
|
|
* \printformatstringdoc
|
|
* \note This function will not block.
|
|
*
|
|
* \param[in] handle Log component handle.
|
|
* \param[in] fmt Format string.
|
|
* \param[in] args List of message arguments.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
#define vmk_Log(handle, fmt, args...) \
|
|
vmk_LogLevel(VMK_LOG_URGENCY_NORMAL, \
|
|
handle, vmk_LogGetCurrentLogLevel(handle), \
|
|
"%s: %s:%d: " fmt "\n", vmk_LogGetName(handle), \
|
|
__FUNCTION__, __LINE__, ##args)
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_Warning -- */ /**
|
|
*
|
|
* \brief Log a warning message to a logging component at its current
|
|
* log level.
|
|
*
|
|
* Should be used to log abnormal conditions.
|
|
*
|
|
* \printformatstringdoc
|
|
* \note This function will not block.
|
|
*
|
|
* \param[in] handle Log component handle.
|
|
* \param[in] fmt Format string.
|
|
* \param[in] args List of message arguments.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
#define vmk_Warning(handle, fmt, args...) \
|
|
vmk_LogLevel(VMK_LOG_URGENCY_WARNING, \
|
|
handle, vmk_LogGetCurrentLogLevel(handle), \
|
|
"%s: %s:%d:" fmt "\n", vmk_LogGetName(handle), \
|
|
__FUNCTION__, __LINE__, ##args)
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_Alert -- */ /**
|
|
*
|
|
* \brief Log an alert message to a logging component at its current
|
|
* log level.
|
|
*
|
|
* Should be used to notify users of system alerts.
|
|
*
|
|
* \printformatstringdoc
|
|
* \note This function will not block.
|
|
*
|
|
* \param[in] handle Log component handle.
|
|
* \param[in] fmt Format string.
|
|
* \param[in] args List of message arguments.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
#define vmk_Alert(handle, fmt, args...) \
|
|
vmk_LogLevel(VMK_LOG_URGENCY_ALERT, \
|
|
handle, vmk_LogGetCurrentLogLevel(handle), \
|
|
"%s: %s:%d:" fmt "\n", vmk_LogGetName(handle), \
|
|
__FUNCTION__, __LINE__, ##args)
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_LogDebugMessage -- */ /**
|
|
*
|
|
* \brief Log an information message to the vmkernel log unconditionally
|
|
* on debug builds only.
|
|
*
|
|
* Should be used to log information messages and non-error conditions
|
|
* when no log component is available.
|
|
*
|
|
* \printformatstringdoc
|
|
* \note This function will not block.
|
|
*
|
|
* \param[in] fmt Format string.
|
|
* \param[in] args List of message arguments.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
#ifndef VMX86_LOG
|
|
#define vmk_LogDebugMessage(fmt, args...)
|
|
#else
|
|
#define vmk_LogDebugMessage(fmt, args...) \
|
|
vmk_LogNoLevel(VMK_LOG_URGENCY_NORMAL, fmt "\n", ##args)
|
|
#endif
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_LogMessage -- */ /**
|
|
*
|
|
* \brief Log an information message to the vmkernel log unconditionally.
|
|
*
|
|
* Should be used to log information messages and non-error conditions
|
|
* when no log component is available.
|
|
*
|
|
* \printformatstringdoc
|
|
* \note This function will not block.
|
|
*
|
|
* \param[in] fmt Format string.
|
|
* \param[in] args List of message arguments.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
#define vmk_LogMessage(fmt, args...) \
|
|
vmk_LogNoLevel(VMK_LOG_URGENCY_NORMAL, fmt "\n", ##args)
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_WarningMessage -- */ /**
|
|
*
|
|
* \brief Log a warning or error message to the vmkernel log
|
|
* unconditionally.
|
|
*
|
|
* Should be used to log abnormal conditions when no log component is
|
|
* available.
|
|
*
|
|
* \printformatstringdoc
|
|
* \note This function will not block.
|
|
*
|
|
* \param[in] fmt Format string.
|
|
* \param[in] args List of message arguments.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
#define vmk_WarningMessage(fmt, args...) \
|
|
vmk_LogNoLevel(VMK_LOG_URGENCY_WARNING, fmt "\n", ##args)
|
|
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_AlertMessage -- */ /**
|
|
*
|
|
* \brief Log a system alert to the vmkernel log and the console
|
|
* unconditionally.
|
|
*
|
|
* Should be used to log severe problems when no log component is
|
|
* available.
|
|
*
|
|
* \printformatstringdoc
|
|
* \note This function will not block.
|
|
*
|
|
* \param[in] fmt Format string.
|
|
* \param[in] args List of message arguments.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
#define vmk_AlertMessage(fmt, args...) \
|
|
vmk_LogNoLevel(VMK_LOG_URGENCY_ALERT, fmt "\n", ##args)
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_LogSetCurrentLogLevel -- */ /**
|
|
*
|
|
* \brief Set current log level of a given log component
|
|
*
|
|
* \note This function will not block.
|
|
*
|
|
* \param[in] handle Log component handle to modify.
|
|
* \param[in] level Log level to set component to.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_LogSetCurrentLogLevel(
|
|
vmk_LogComponent handle,
|
|
vmk_int32 level);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_vLogLevel -- */ /**
|
|
*
|
|
* \brief Log a message using a log component
|
|
*
|
|
* \printformatstringdoc
|
|
* \note This function will not block.
|
|
*
|
|
* Output a log message to the vmkernel log if the current log level
|
|
* on the given log component is equal to or greater than the given
|
|
* log level.
|
|
*
|
|
* \param[in] urgency How urgent the message is.
|
|
* \param[in] handle Log component handle.
|
|
* \param[in] level Minimum log level the component must be set to
|
|
* in order to print the message.
|
|
* \param[in] fmt Format string.
|
|
* \param[in] ap List of message arguments.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_vLogLevel(
|
|
vmk_LogUrgency urgency,
|
|
vmk_LogComponent handle,
|
|
vmk_int32 level,
|
|
const char *fmt,
|
|
va_list ap);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_LogLevel -- */ /**
|
|
*
|
|
* \brief Log a message using a log component
|
|
*
|
|
* \printformatstringdoc
|
|
* \note This function will not block.
|
|
*
|
|
* Output a log message to the vmkernel log if the current log level
|
|
* on the given log component is equal to or greater than the given
|
|
* log level.
|
|
*
|
|
*
|
|
* \param[in] urgency How urgent the message is.
|
|
* \param[in] handle Log component handle.
|
|
* \param[in] level Minimum log level the component must be set to
|
|
* in order to print the message.
|
|
* \param[in] fmt Format string.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_LogLevel(
|
|
vmk_LogUrgency urgency,
|
|
vmk_LogComponent handle,
|
|
vmk_int32 level,
|
|
const char *fmt,
|
|
...)
|
|
VMK_ATTRIBUTE_PRINTF(4,5);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_vLogNoLevel -- */ /**
|
|
*
|
|
* \brief Log an information message to the vmkernel log
|
|
* unconditionally with a va_list.
|
|
*
|
|
* \printformatstringdoc
|
|
* \note This function will not block.
|
|
*
|
|
* Should be used to log information messages and non-error conditions
|
|
* when no log component is available.
|
|
*
|
|
* \param[in] urgency How urgent the message is.
|
|
* \param[in] fmt Format string.
|
|
* \param[in] ap List of message arguments.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_vLogNoLevel(
|
|
vmk_LogUrgency urgency,
|
|
const char *fmt,
|
|
va_list ap);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_LogNoLevel -- */ /**
|
|
*
|
|
* \brief Log an information message to the vmkernel log
|
|
* unconditionally with variable arguments.
|
|
*
|
|
* \printformatstringdoc
|
|
* \note This function will not block.
|
|
*
|
|
* Should be used to log information messages and non-error conditions
|
|
* when no log component is available.
|
|
*
|
|
*
|
|
* \param[in] urgency How urgent the message is.
|
|
* \param[in] fmt Format string.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_LogNoLevel(
|
|
vmk_LogUrgency urgency,
|
|
const char *fmt,
|
|
...)
|
|
VMK_ATTRIBUTE_PRINTF(2,3);
|
|
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_LogFindLogComponentByName -- */ /**
|
|
*
|
|
* \brief Get a log component by the given log component name and
|
|
* the module ID.
|
|
*
|
|
* \note This function will not block.
|
|
*
|
|
* \param[in] id Module ID that registered the log component
|
|
* \param[in] name Log component name
|
|
* \param[out] handle Returns log component handle of the specified
|
|
* name and the module ID.
|
|
*
|
|
* \retval VMK_NOT_FOUND The given log component name does not exist.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_LogFindLogComponentByName(
|
|
vmk_ModuleID id,
|
|
const vmk_Name *name,
|
|
vmk_LogComponent *handle);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_LogBacktrace -- */ /**
|
|
*
|
|
* \brief Write the current stack backtrace to a log component.
|
|
*
|
|
* \note This function will not block.
|
|
*
|
|
* This routine logs at the component's current logging level and
|
|
* at NORMAL urgency.
|
|
*
|
|
* \param[in] handle Log component to write the backtrace to.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_LogBacktrace(
|
|
vmk_LogComponent handle);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_LogBacktraceMessage -- */ /**
|
|
*
|
|
* \brief Write the current stack backtrace to the vmkernel log.
|
|
*
|
|
* \note This function will not block.
|
|
*
|
|
* Should be used to log the backtrace when no logging component
|
|
* is available.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_LogBacktraceMessage(void);
|
|
|
|
#endif /* _VMKAPI_LOGGING_H_ */
|
|
/** @} */
|
|
/** @} */
|