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 */ 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