1 /*
2  * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved.
3  * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved.
4  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
5  *
6  * This software is available to you under a choice of one of two
7  * licenses.  You may choose to be licensed under the terms of the GNU
8  * General Public License (GPL) Version 2, available from the file
9  * COPYING in the main directory of this source tree, or the
10  * OpenIB.org BSD license below:
11  *
12  *     Redistribution and use in source and binary forms, with or
13  *     without modification, are permitted provided that the following
14  *     conditions are met:
15  *
16  *      - Redistributions of source code must retain the above
17  *        copyright notice, this list of conditions and the following
18  *        disclaimer.
19  *
20  *      - Redistributions in binary form must reproduce the above
21  *        copyright notice, this list of conditions and the following
22  *        disclaimer in the documentation and/or other materials
23  *        provided with the distribution.
24  *
25  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
26  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
27  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
28  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
29  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
30  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
31  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
32  * SOFTWARE.
33  *
34  */
35 
36 /*
37  * Abstract:
38  *	Declaration of logging mechanisms.
39  */
40 
41 #ifndef _CL_LOG_H_
42 #define _CL_LOG_H_
43 
44 #include <complib/cl_types.h>
45 
46 #ifdef __cplusplus
47 #  define BEGIN_C_DECLS extern "C" {
48 #  define END_C_DECLS   }
49 #else				/* !__cplusplus */
50 #  define BEGIN_C_DECLS
51 #  define END_C_DECLS
52 #endif				/* __cplusplus */
53 
54 BEGIN_C_DECLS
55 /****h* Component Library/Log Provider
56 * NAME
57 *	Log Provider
58 *
59 * DESCRIPTION
60 *	The log provider allows users to log information in a system log instead of
61 *	the console or debugger target.
62 **********/
63 /****d* Component Library: Log Provider/cl_log_type_t
64 * NAME
65 *	cl_log_type_t
66 *
67 * DESCRIPTION
68 *	The cl_log_type_t enumerated type is used to differentiate between
69 *	different types of log entries.
70 *
71 * SYNOPSIS
72 */
73 typedef enum _cl_log_type {
74 	CL_LOG_INFO,
75 	CL_LOG_WARN,
76 	CL_LOG_ERROR
77 } cl_log_type_t;
78 /*
79 * VALUES
80 *	CL_LOG_INFO
81 *		Indicates a log entry is purely informational.
82 *
83 *	CL_LOG_WARN
84 *		Indicates a log entry is a warning but non-fatal.
85 *
86 *	CL_LOG_ERROR
87 *		Indicates a log entry is a fatal error.
88 *
89 * SEE ALSO
90 *	Log Provider, cl_log_event
91 *********/
92 
93 /****f* Component Library: Log Provider/cl_log_event
94 * NAME
95 *	cl_log_event
96 *
97 * DESCRIPTION
98 *	The cl_log_event function adds a new entry to the system log.
99 *
100 * SYNOPSIS
101 */
102 void
103 cl_log_event(IN const char *const name,
104 	     IN const cl_log_type_t type,
105 	     IN const char *const message,
106 	     IN const void *const p_data OPTIONAL, IN const uint32_t data_len);
107 /*
108 * PARAMETERS
109 *	name
110 *		[in] Pointer to an ANSI string containing the name of the source for
111 *		the log entry.
112 *
113 *	type
114 *		[in] Defines the type of log entry to add to the system log.
115 *		See the definition of cl_log_type_t for acceptable values.
116 *
117 *	message
118 *		[in] Pointer to an ANSI string containing the text for the log entry.
119 *		The message should not be terminated with a new line, as the log
120 *		provider appends a new line to all log entries.
121 *
122 *	p_data
123 *		[in] Optional pointer to data providing context for the log entry.
124 *		At most 256 bytes of data can be successfully logged.
125 *
126 *	data_len
127 *		[in] Length of the buffer pointed to by the p_data parameter.  Ignored
128 *		if p_data is NULL.
129 *
130 * RETURN VALUE
131 *	This function does not return a value.
132 *
133 * NOTES
134 *	If the data length exceeds the maximum supported, the event is logged
135 *	without its accompanying data.
136 *
137 * SEE ALSO
138 *	Log Provider, cl_log_type_t
139 *********/
140 
141 END_C_DECLS
142 #endif				/* _CL_LOG_H_ */
143