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