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