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
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#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*/
282typedef 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. */
313extern 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*/
326void 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*/
414typedef 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*/
446static 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
471END_C_DECLS
472#endif				/* _DATA_TYPES_H_ */
473