contrib/ofed/management/opensm/include/complib/cl_types.h

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