1 /*
2 * Copyright (c) 2004-2009 Voltaire, Inc. All rights reserved.
3 * Copyright (c) 2002-2010 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 * Defines standard return codes, keywords, macros, and debug levels.
39 */
40
41 #ifdef __WIN__
42 #pragma warning(disable : 4996)
43 #endif
44
45 #ifndef _CL_TYPES_H_
46 #define _CL_TYPES_H_
47
48 #ifdef __cplusplus
49 # define BEGIN_C_DECLS extern "C" {
50 # define END_C_DECLS }
51 #else /* !__cplusplus */
52 # define BEGIN_C_DECLS
53 # define END_C_DECLS
54 #endif /* __cplusplus */
55
56 BEGIN_C_DECLS
57 #include <complib/cl_types_osd.h>
58 #include <stddef.h>
59 typedef uint16_t net16_t;
60 typedef uint32_t net32_t;
61 typedef uint64_t net64_t;
62
63 /* explicit cast of void* to uint32_t */
64 #ifndef ASSERT_VOIDP2UINTN
65 #if __WORDSIZE == 64
66 #define ASSERT_VOIDP2UINTN(var) \
67 CL_ASSERT( (intptr_t)var <= 0xffffffffffffffffL )
68 #else /* __WORDSIZE == 64 */
69 #if __WORDSIZE == 32
70 /* need to cast carefully to avoid the warining of un-needed check */
71 #define ASSERT_VOIDP2UINTN(var) \
72 CL_ASSERT( (intptr_t)var <= 0x100000000ULL )
73 #else /* __WORDSIZE == 32 */
74 #error "Need to know WORDSIZE to tell how to cast to unsigned long int"
75 #endif /* __WORDSIZE == 32 */
76 #endif /* __WORDSIZE == 64 */
77 #endif
78
79 /* explicit casting of void* to long */
80 #ifndef CAST_P2LONG
81 #define CAST_P2LONG(var) ((intptr_t)(var))
82 #endif
83
84 /****d* Component Library: Pointer Manipulation/offsetof
85 * NAME
86 * offsetof
87 *
88 * DESCRIPTION
89 * The offsetof macro returns the offset of a member within a structure.
90 *
91 * SYNOPSIS
92 * uintptr_t
93 * offsetof(
94 * IN TYPE,
95 * IN MEMBER );
96 *
97 * PARAMETERS
98 * TYPE
99 * [in] Name of the structure containing the specified member.
100 *
101 * MEMBER
102 * [in] Name of the member whose offset in the specified structure
103 * is to be returned.
104 *
105 * RETURN VALUE
106 * Number of bytes from the beginning of the structure to the
107 * specified member.
108 *
109 * SEE ALSO
110 * PARENT_STRUCT
111 *********/
112 #ifndef offsetof
113 #define offsetof(TYPE, MEMBER) ((uintptr_t) &((TYPE *)0)->MEMBER)
114 #endif
115
116 /****d* Component Library: Pointer Manipulation/PARENT_STRUCT
117 * NAME
118 * PARENT_STRUCT
119 *
120 * DESCRIPTION
121 * The PARENT_STRUCT macro returns a pointer to a structure
122 * given a name and pointer to one of its members.
123 *
124 * SYNOPSIS
125 * PARENT_TYPE*
126 * PARENT_STRUCT(
127 * IN void* const p_member,
128 * IN PARENT_TYPE,
129 * IN MEMBER_NAME );
130 *
131 * PARAMETERS
132 * p_member
133 * [in] Pointer to the MEMBER_NAME member of a PARENT_TYPE structure.
134 *
135 * PARENT_TYPE
136 * [in] Name of the structure containing the specified member.
137 *
138 * MEMBER_NAME
139 * [in] Name of the member whose address is passed in the p_member
140 * parameter.
141 *
142 * RETURN VALUE
143 * Pointer to a structure of type PARENT_TYPE whose MEMBER_NAME member is
144 * located at p_member.
145 *
146 * SEE ALSO
147 * offsetof
148 *********/
149 #define PARENT_STRUCT(p_member, PARENT_TYPE, MEMBER_NAME) \
150 ((PARENT_TYPE*)((uint8_t*)(p_member) - offsetof(PARENT_TYPE, MEMBER_NAME)))
151
152 /****d* Component Library/Parameter Keywords
153 * NAME
154 * Parameter Keywords
155 *
156 * DESCRIPTION
157 * The Parameter Keywords can be used to clarify the usage of function
158 * parameters to users.
159 *
160 * VALUES
161 * IN
162 * Designates that the parameter is used as input to a function.
163 *
164 * OUT
165 * Designates that the parameter's value will be set by the function.
166 *
167 * OPTIONAL
168 * Designates that the parameter is optional, and may be NULL.
169 * The OPTIONAL keyword, if used, follows the parameter name.
170 *
171 * EXAMPLE
172 * // Function declaration.
173 * void*
174 * my_func(
175 * IN void* const p_param1,
176 * OUT void** const p_handle OPTIONAL );
177 *
178 * NOTES
179 * Multiple keywords can apply to a single parameter. The IN and OUT
180 * keywords precede the parameter type. The OPTIONAL
181 * keyword, if used, follows the parameter name.
182 *********/
183 #ifndef IN
184 #define IN /* Function input parameter */
185 #endif
186 #ifndef OUT
187 #define OUT /* Function output parameter */
188 #endif
189 #ifndef OPTIONAL
190 #define OPTIONAL /* Optional function parameter - NULL if not used */
191 #endif
192
193 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
194 %% Function Returns And Completion Codes %%
195 %% %%
196 %% The text for any addition to this enumerated type must be added to the %%
197 %% string array defined in <cl_statustext.c>. %%
198 %% %%
199 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
200
201 /****d* Component Library/Data Types
202 * NAME
203 * Data Types
204 *
205 * DESCRIPTION
206 * The component library provides and uses explicitly sized types.
207 *
208 * VALUES
209 * char
210 * 8-bit, defined by compiler.
211 *
212 * void
213 * 0-bit, defined by compiler.
214 *
215 * int8_t
216 * 8-bit signed integer.
217 *
218 * uint8_t
219 * 8-bit unsigned integer.
220 *
221 * int16_t
222 * 16-bit signed integer.
223 *
224 * uint16_t
225 * 16-bit unsigned integer.
226 *
227 * net16_t
228 * 16-bit network byte order value.
229 *
230 * int32_t
231 * 32-bit signed integer.
232 *
233 * uint32_t
234 * 32-bit unsigned integer.
235 *
236 * net32_t
237 * 32-bit network byte order value.
238 *
239 * int64_t
240 * 64-bit signed integer.
241 *
242 * uint64_t
243 * 64-bit unsigned integer.
244 *
245 * net64_t
246 * 64-bit network byte order value.
247 *
248 * boolean_t
249 * integral sized. Set to TRUE or FALSE and used in logical expressions.
250 *
251 * NOTES
252 * Pointer types are not defined as these provide no value and can potentially
253 * lead to naming confusion.
254 *********/
255
256 /****d* Component Library: Data Types/cl_status_t
257 * NAME
258 * cl_status_t
259 *
260 * DESCRIPTION
261 * The cl_status_t return types are used by the component library to
262 * provide detailed function return values.
263 *
264 * SYNOPSIS
265 */
266 #define CL_SUCCESS 0
267 #define CL_ERROR 1
268 #define CL_INVALID_STATE 2
269 #define CL_INVALID_OPERATION 3
270 #define CL_INVALID_SETTING 4
271 #define CL_INVALID_PARAMETER 5
272 #define CL_INSUFFICIENT_RESOURCES 6
273 #define CL_INSUFFICIENT_MEMORY 7
274 #define CL_INVALID_PERMISSION 8
275 #define CL_COMPLETED 9
276 #define CL_NOT_DONE 10
277 #define CL_PENDING 11
278 #define CL_TIMEOUT 12
279 #define CL_CANCELED 13
280 #define CL_REJECT 14
281 #define CL_OVERRUN 15
282 #define CL_NOT_FOUND 16
283 #define CL_UNAVAILABLE 17
284 #define CL_BUSY 18
285 #define CL_DISCONNECT 19
286 #define CL_DUPLICATE 20
287 #define CL_STATUS_COUNT 21 /* should be the last value */
288
289 typedef int cl_status_t;
290 /*
291 * SEE ALSO
292 * Data Types, CL_STATUS_MSG
293 *********/
294
295 /* Status values above converted to text for easier printing. */
296 extern const char *cl_status_text[];
297
298 #ifndef cl_panic
299 /****f* Component Library: Error Trapping/cl_panic
300 * NAME
301 * cl_panic
302 *
303 * DESCRIPTION
304 * Halts execution of the current process. Halts the system if called in
305 * from the kernel.
306 *
307 * SYNOPSIS
308 */
309 void cl_panic(IN const char *const message, IN ...);
310 /*
311 * PARAMETERS
312 * message
313 * [in] ANSI string formatted identically as for a call to the standard C
314 * function printf describing the cause for the panic.
315 *
316 * ...
317 * [in] Extra parameters for string formatting, as defined for the
318 * standard C function printf.
319 *
320 * RETURN VALUE
321 * This function does not return.
322 *
323 * NOTES
324 * The formatting of the message string is the same as for printf
325 *
326 * cl_panic sends the message to the current message logging target.
327 *********/
328 #endif /* cl_panic */
329
330 /****d* Component Library: Data Types/CL_STATUS_MSG
331 * NAME
332 * CL_STATUS_MSG
333 *
334 * DESCRIPTION
335 * The CL_STATUS_MSG macro returns a textual representation of
336 * an cl_status_t code.
337 *
338 * SYNOPSIS
339 * const char*
340 * CL_STATUS_MSG(
341 * IN cl_status_t errcode );
342 *
343 * PARAMETERS
344 * errcode
345 * [in] cl_status_t code for which to return a text representation.
346 *
347 * RETURN VALUE
348 * Pointer to a string containing a textual representation of the errcode
349 * parameter.
350 *
351 * NOTES
352 * This function performs boundary checking on the cl_status_t value,
353 * masking off the upper 24-bits. If the value is out of bounds, the string
354 * "invalid status code" is returned.
355 *
356 * SEE ALSO
357 * cl_status_t
358 *********/
359 #define CL_STATUS_MSG( errcode ) \
360 ((errcode < CL_STATUS_COUNT)?cl_status_text[errcode]:"invalid status code")
361
362 #if !defined( FALSE )
363 #define FALSE 0
364 #endif /* !defined( FALSE ) */
365
366 #if !defined( TRUE )
367 #define TRUE (!FALSE)
368 #endif /* !defined( TRUE ) */
369
370 /****d* Component Library: Unreferenced Parameters/UNUSED_PARAM
371 * NAME
372 * UNUSED_PARAM
373 *
374 * DESCRIPTION
375 * The UNUSED_PARAM macro can be used to eliminates compiler warnings related
376 * to intentionally unused formal parameters in function implementations.
377 *
378 * SYNOPSIS
379 * UNUSED_PARAM( P )
380 *
381 * EXAMPLE
382 * void my_func( int32_t value )
383 * {
384 * UNUSED_PARAM( value );
385 * }
386 *********/
387
388 /****d* Component Library/Object States
389 * NAME
390 * Object States
391 *
392 * DESCRIPTION
393 * The object states enumerated type defines the valid states of components.
394 *
395 * SYNOPSIS
396 */
397 typedef enum _cl_state {
398 CL_UNINITIALIZED = 1,
399 CL_INITIALIZED,
400 CL_DESTROYING,
401 CL_DESTROYED
402 } cl_state_t;
403 /*
404 * VALUES
405 * CL_UNINITIALIZED
406 * Indicates that initialization was not invoked successfully.
407 *
408 * CL_INITIALIZED
409 * Indicates initialization was successful.
410 *
411 * CL_DESTROYING
412 * Indicates that the object is undergoing destruction.
413 *
414 * CL_DESTROYED
415 * Indicates that the object's destructor has already been called. Most
416 * objects set their final state to CL_DESTROYED before freeing the
417 * memory associated with the object.
418 *********/
419
420 /****d* Component Library: Object States/cl_is_state_valid
421 * NAME
422 * cl_is_state_valid
423 *
424 * DESCRIPTION
425 * The cl_is_state_valid function returns whether a state has a valid value.
426 *
427 * SYNOPSIS
428 */
cl_is_state_valid(IN const cl_state_t state)429 static inline boolean_t cl_is_state_valid(IN const cl_state_t state)
430 {
431 return ((state == CL_UNINITIALIZED) || (state == CL_INITIALIZED) ||
432 (state == CL_DESTROYING) || (state == CL_DESTROYED));
433 }
434
435 /*
436 * PARAMETERS
437 * state
438 * State whose value to validate.
439 *
440 * RETURN VALUES
441 * TRUE if the specified state has a valid value.
442 *
443 * FALSE otherwise.
444 *
445 * NOTES
446 * This function is used in debug builds to check for valid states. If an
447 * uninitialized object is passed, the memory for the state may cause the
448 * state to have an invalid value.
449 *
450 * SEE ALSO
451 * Object States
452 *********/
453
454 END_C_DECLS
455 #endif /* _DATA_TYPES_H_ */
456