sys/dev/isci/scil/sci_logger.h

   1 /*-
   2  * This file is provided under a dual BSD/GPLv2 license.  When using or
   3  * redistributing this file, you may do so under either license.
   4  *
   5  * GPL LICENSE SUMMARY
   6  *
   7  * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of version 2 of the GNU General Public License as
  11  * published by the Free Software Foundation.
  12  *
  13  * This program is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA.
  21  * The full GNU General Public License is included in this distribution
  22  * in the file called LICENSE.GPL.
  23  *
  24  * BSD LICENSE
  25  *
  26  * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
  27  * All rights reserved.
  28  *
  29  * Redistribution and use in source and binary forms, with or without
  30  * modification, are permitted provided that the following conditions
  31  * are met:
  32  *
  33  *   * Redistributions of source code must retain the above copyright
  34  *     notice, this list of conditions and the following disclaimer.
  35  *   * Redistributions in binary form must reproduce the above copyright
  36  *     notice, this list of conditions and the following disclaimer in
  37  *     the documentation and/or other materials provided with the
  38  *     distribution.
  39  *
  40  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  41  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  42  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  43  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  44  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  45  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  46  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  47  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  48  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  49  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  50  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  51  *
  52  * $FreeBSD$
  53  */
  54 #ifndef _SCI_LOGGER_H_
  55 #define _SCI_LOGGER_H_
  56
  57 /**
  58  * @file
  59  *
  60  * @brief This file contains all of the interface methods that can be called
  61  *        by an SCI user on the logger object.  These methods should be
  62  *        utilized to control the amount of information being logged by the
  63  *        SCI implementation.
  64  */
  65
  66 #ifdef __cplusplus
  67 extern "C" {
  68 #endif // __cplusplus
  69
  70 #include <dev/isci/scil/sci_types.h>
  71
  72
  73 /* The following is a list of verbosity levels that can be used to enable */
  74 /* logging for specific log objects.                                      */
  75
  76 /** Enable/disable error level logging for the associated logger object(s). */
  77 #define SCI_LOG_VERBOSITY_ERROR      0x00
  78
  79 /** Enable/disable warning level logging for the associated logger object(s). */
  80 #define SCI_LOG_VERBOSITY_WARNING    0x01
  81
  82 /**
  83  * Enable/disable informative level logging for the associated logger object(s).
  84  */
  85 #define SCI_LOG_VERBOSITY_INFO       0x02
  86
  87 /**
  88  * This constant is used to enable function trace (enter/exit) level
  89  * logging for the associated log object(s).
  90  */
  91 #define SCI_LOG_VERBOSITY_TRACE      0x03
  92
  93 /**
  94  * This constant is used to enable state tracing information it will emit a
  95  * log message each time a state is entered for the associated log object(s).
  96  */
  97 #define SCI_LOG_VERBOSITY_STATES     0x04
  98
  99 #ifdef SCI_LOGGING
 100
 101 /**
 102  * @brief This method will return the verbosity levels enabled for the object
 103  *        listed in the log_object parameter.
 104  * @note  Logging must be enabled at compile time in the driver, otherwise
 105  *        calling this method has no affect.
 106  *
 107  * @param[in]  logger This parameter specifies the logger for which to
 108  *             disable the supplied objects/verbosities.  For example,
 109  *             the framework and core components have different loggers.
 110  * @param[in]  log_object This parameter specifies the log object for which
 111  *             to retrieve the associated verbosity levels.
 112  *             @note This parameter is not a mask, but rather a discrete
 113  *             value.
 114  *
 115  * @return This method will return the verbosity levels enabled for the
 116  *         supplied log object.
 117  * @retval SCI_LOGGER_VERBOSITY_ERROR This value indicates that the error
 118  *         verbosity level was set for the supplied log_object.
 119  * @retval SCI_LOGGER_VERBOSITY_WARNING This value indicates that the warning
 120  *         verbosity level was set for the supplied log_object.
 121  * @retval SCI_LOGGER_VERBOSITY_INFO This value indicates that the
 122  *         informational verbosity level was set for the supplied log_object.
 123  * @retval SCI_LOGGER_VERBOSITY_TRACE This value indicates that the trace
 124  *         verbosity level was set for the supplied log_object.
 125  * @retval SCI_LOGGER_VERBOSITY_STATES This value indicates that the states
 126  *         transition verbosity level was set for the supplied log_object
 127  */
 128 U8 sci_logger_get_verbosity_mask(
 129    SCI_LOGGER_HANDLE_T  logger,
 130    U32                  log_object
 131 );
 132
 133 /**
 134  * @brief This method simply returns the log object mask.  This mask
 135  *        is essentially a list of log objects for which the specified
 136  *        level (verbosity) is enabled.
 137  * @note  Logging must be enabled at compile time in the driver, otherwise
 138  *        calling this method has no affect.
 139  * @note  Reserved bits in both the supplied masks shall be ignored.
 140  *
 141  * @param[in]  logger This parameter specifies the logger for which to
 142  *             disable the supplied objects/verbosities.  For example,
 143  *             the framework and core components have different loggers.
 144  * @param[in]  verbosity This parameter specifies the verbosity for which
 145  *             to retrieve the set of enabled log objects.  Valid values for
 146  *             this parameter are:
 147  *                -# SCI_LOGGER_VERBOSITY_ERROR
 148  *                -# SCI_LOGGER_VERBOSITY_WARNING
 149  *                -# SCI_LOGGER_VERBOSITY_INFO
 150  *                -# SCI_LOGGER_VERBOSITY_TRACE
 151  *                -# SCI_LOGGER_VERBOSITY_STATES
 152  *             @note This parameter is not a mask, but rather a discrete
 153  *             value.
 154  *
 155  * @return This method will return the log object mask indicating each of
 156  *         the log objects for which logging is enabled at the supplied level.
 157  */
 158 U32 sci_logger_get_object_mask(
 159    SCI_LOGGER_HANDLE_T  logger,
 160    U8                   verbosity
 161 );
 162
 163 /**
 164  * @brief This method will enable each of the supplied log objects in
 165  *        log_object_mask for each of the supplied verbosities in
 166  *        verbosity_mask.  To enable all logging, simply set all bits in
 167  *        both the log_object_mask and verbosity_mask.
 168  * @note  Logging must be enabled at compile time in the driver, otherwise
 169  *        calling this method has no affect.
 170  * @note  Reserved bits in both the supplied masks shall be ignored.
 171  *
 172  * @param[in]  logger This parameter specifies the logger for which to
 173  *             disable the supplied objects/verbosities.  For example,
 174  *             the framework and core components have different loggers.
 175  * @param[in]  log_object_mask This parameter specifies the log objects for
 176  *             which to enable logging.
 177  * @param[in]  verbosity_mask This parameter specifies the verbosity levels
 178  *             at which to enable each log_object.
 179  *
 180  * @return none
 181  */
 182 void sci_logger_enable(
 183    SCI_LOGGER_HANDLE_T  logger,
 184    U32                  log_object_mask,
 185    U8                   verbosity_mask
 186 );
 187
 188 /**
 189  * @brief This method will disable each of the supplied log objects in
 190  *        log_object_mask for each of the supplied verbosities in
 191  *        verbosity_mask.  To disable all logging, simply set all bits in
 192  *        both the log_object_mask and verbosity_mask.
 193  * @note  Logging must be enabled at compile time in the driver, otherwise
 194  *        calling this method has no affect.
 195  * @note  Reserved bits in both the supplied masks shall be ignored.
 196  *
 197  * @param[in]  logger This parameter specifies the logger for which to
 198  *             disable the supplied objects/verbosities.  For example,
 199  *             the framework and core components have different loggers.
 200  * @param[in]  log_object_mask This parameter specifies the log objects for
 201  *             which to disable logging.
 202  * @param[in]  verbosity_mask This parameter specifies the verbosity levels
 203  *             at which to disable each log_object.
 204  *
 205  * @return none
 206  */
 207 void sci_logger_disable(
 208    SCI_LOGGER_HANDLE_T  logger,
 209    U32                  log_object_mask,
 210    U8                   verbosity_mask
 211 );
 212
 213
 214 /**
 215  * @brief this macro checks whether it is ok to log.
 216  *
 217  * @param[in]  logger This parameter specifies the logger for
 218  *             which to disable the supplied
 219  *             objects/verbosities.  For example, the framework
 220  *             and core components have different loggers.
 221  * @param[in]  log_object_mask This parameter specifies the log objects for
 222  *             which to disable logging.
 223  * @param[in]  verbosity_mask This parameter specifies the verbosity levels
 224  *             at which to disable each log_object.
 225  *
 226  * @return TRUE or FALSE
 227  */
 228 BOOL sci_logger_is_enabled(
 229    SCI_LOGGER_HANDLE_T  logger,
 230    U32                  log_object_mask,
 231    U8                   verbosity_mask
 232 );
 233
 234
 235 #else // SCI_LOGGING
 236
 237 #define sci_logger_get_verbosity_mask(logger, log_object)
 238 #define sci_logger_get_object_mask(logger, verbosity)
 239 #define sci_logger_enable(logger, log_object_mask, verbosity_mask)
 240 #define sci_logger_disable(logger, log_object_mask, verbosity_mask)
 241 #define sci_logger_is_enabled(logger, log_object_mask, verbosity_level)
 242
 243 #endif // SCI_LOGGING
 244
 245 #ifdef __cplusplus
 246 }
 247 #endif // __cplusplus
 248
 249 #endif // _SCI_LOGGER_H_
 250