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