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
56BEGIN_C_DECLS
57#include <complib/cl_types_osd.h>
58#include <stddef.h>
59typedef uint16_t net16_t;
60typedef uint32_t net32_t;
61typedef 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
289typedef 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. */
296extern 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*/
309void 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*/
397typedef 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*/
429static 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
454END_C_DECLS
455#endif				/* _DATA_TYPES_H_ */
456