[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_types.h
1 /*\r
2  * Copyright (c) 2005 SilverStorm Technologies.  All rights reserved.\r
3  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. \r
4  *\r
5  * This software is available to you under the OpenIB.org BSD license\r
6  * below:\r
7  *\r
8  *     Redistribution and use in source and binary forms, with or\r
9  *     without modification, are permitted provided that the following\r
10  *     conditions are met:\r
11  *\r
12  *      - Redistributions of source code must retain the above\r
13  *        copyright notice, this list of conditions and the following\r
14  *        disclaimer.\r
15  *\r
16  *      - Redistributions in binary form must reproduce the above\r
17  *        copyright notice, this list of conditions and the following\r
18  *        disclaimer in the documentation and/or other materials\r
19  *        provided with the distribution.\r
20  *\r
21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,\r
22  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\r
23  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\r
24  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\r
25  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\r
26  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
27  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r
28  * SOFTWARE.\r
29  *\r
30  * $Id$\r
31  */\r
32 \r
33 \r
34 /*\r
35  * Abstract:\r
36  *      Defines standard return codes, keywords, macros, and debug levels.\r
37  *\r
38  * Environment:\r
39  *      All supported platforms\r
40  */\r
41 \r
42 \r
43 #ifndef _CL_TYPES_H_\r
44 #define _CL_TYPES_H_\r
45 \r
46 \r
47 #include <complib/cl_types_osd.h>\r
48 \r
49 \r
50 typedef uint16_t                net16_t;\r
51 typedef uint32_t                net32_t;\r
52 typedef uint64_t                net64_t;\r
53 \r
54 \r
55 \r
56 /****d* Component Library: Pointer Manipulation/offsetof\r
57 * NAME\r
58 *       offsetof\r
59 *\r
60 * DESCRIPTION\r
61 *       The offsetof macro returns the offset of a member within a structure.\r
62 *\r
63 * SYNOPSIS\r
64 *       uintn_t\r
65 *       offsetof(\r
66 *               IN TYPE,\r
67 *               IN MEMBER );\r
68 *\r
69 * PARAMETERS\r
70 *       TYPE\r
71 *               [in] Name of the structure containing the specified member.\r
72 *\r
73 *       MEMBER\r
74 *               [in] Name of the member whose offset in the specified structure\r
75 *               is to be returned.\r
76 *\r
77 * RETURN VALUE\r
78 *       Number of bytes from the beginning of the structure to the\r
79 *       specified member.\r
80 *\r
81 * SEE ALSO\r
82 *       PARENT_STRUCT\r
83 *********/\r
84 #ifndef offsetof\r
85 #define offsetof(TYPE, MEMBER) ((uintn_t) &((TYPE *)0)->MEMBER)\r
86 #endif\r
87 \r
88 \r
89 /****d* Component Library: Pointer Manipulation/PARENT_STRUCT\r
90 * NAME\r
91 *       PARENT_STRUCT\r
92 *\r
93 * DESCRIPTION\r
94 *       The PARENT_STRUCT macro returns a pointer to a structure\r
95 *       given a name and pointer to one of its members.\r
96 *\r
97 * SYNOPSIS\r
98 *       PARENT_TYPE*\r
99 *       PARENT_STRUCT(\r
100 *               IN void* const p_member,\r
101 *               IN PARENT_TYPE,\r
102 *               IN MEMBER_NAME );\r
103 *\r
104 * PARAMETERS\r
105 *       p_member\r
106 *               [in] Pointer to the MEMBER_NAME member of a PARENT_TYPE structure.\r
107 *\r
108 *       PARENT_TYPE\r
109 *               [in] Name of the structure containing the specified member.\r
110 *\r
111 *       MEMBER_NAME\r
112 *               [in] Name of the member whose address is passed in the p_member\r
113 *               parameter.\r
114 *\r
115 * RETURN VALUE\r
116 *       Pointer to a structure of type PARENT_TYPE whose MEMBER_NAME member is\r
117 *       located at p_member.\r
118 *\r
119 * SEE ALSO\r
120 *       offsetof\r
121 *********/\r
122 #ifndef PARENT_STRUCT\r
123 #define PARENT_STRUCT(p_member, PARENT_TYPE, MEMBER_NAME) \\r
124         ((PARENT_TYPE*)((uint8_t*)(p_member) - offsetof(PARENT_TYPE, MEMBER_NAME)))\r
125 #endif\r
126 \r
127 /****d* Component Library/Parameter Keywords\r
128 * NAME\r
129 *       Parameter Keywords\r
130 *\r
131 * DESCRIPTION\r
132 *       The Parameter Keywords can be used to clarify the usage of function\r
133 *       parameters to users.\r
134 *\r
135 * VALUES\r
136 *       IN\r
137 *               Designates that the parameter is used as input to a function.\r
138 *\r
139 *       OUT\r
140 *               Designates that the parameter's value will be set by the function.\r
141 *\r
142 *       OPTIONAL\r
143 *               Designates that the parameter is optional, and may be NULL.\r
144 *               The OPTIONAL keyword, if used, follows the parameter name.\r
145 *\r
146 * EXAMPLE\r
147 *       // Function declaration.\r
148 *       void*\r
149 *       my_func(\r
150 *           IN void* const p_param1,\r
151 *           OUT void** const p_handle OPTIONAL );\r
152 *\r
153 * NOTES\r
154 *       Multiple keywords can apply to a single parameter. The IN and OUT\r
155 *       keywords precede the parameter type. The OPTIONAL\r
156 *       keyword, if used, follows the parameter name.\r
157 *********/\r
158 #ifndef         IN\r
159 #define         IN                      /* Function input parameter */\r
160 #endif\r
161 #ifndef         OUT\r
162 #define         OUT                     /* Function output parameter */\r
163 #endif\r
164 #ifndef         OPTIONAL\r
165 #define         OPTIONAL        /* Optional function parameter - NULL if not used */\r
166 #endif\r
167 \r
168 \r
169 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\r
170 %%                  Function Returns And Completion Codes                                        %%\r
171 %%                                                                                                                                                       %%\r
172 %% The text for any addition to this enumerated type must be added to the        %%\r
173 %% string array defined in <cl_statustext.c>.                                                            %%\r
174 %%                                                                                                                                                       %%\r
175 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/\r
176 \r
177 \r
178 /****d* Component Library/Data Types\r
179 * NAME\r
180 *       Data Types\r
181 *\r
182 * DESCRIPTION\r
183 *       The component library provides and uses explicitly sized types.\r
184 *\r
185 * VALUES\r
186 *       char\r
187 *               8-bit, defined by compiler.\r
188 *\r
189 *       void\r
190 *               0-bit, defined by compiler.\r
191 *\r
192 *       int8_t\r
193 *               8-bit signed integer.\r
194 *\r
195 *       uint8_t\r
196 *               8-bit unsigned integer.\r
197 *\r
198 *       int16_t\r
199 *               16-bit signed integer.\r
200 *\r
201 *       uint16_t\r
202 *               16-bit unsigned integer.\r
203 *\r
204 *       net16_t\r
205 *               16-bit network byte order value.\r
206 *\r
207 *       int32_t\r
208 *               32-bit signed integer.\r
209 *\r
210 *       uint32_t\r
211 *               32-bit unsigned integer.\r
212 *\r
213 *       net32_t\r
214 *               32-bit network byte order value.\r
215 *\r
216 *       int64_t\r
217 *               64-bit signed integer.\r
218 *\r
219 *       uint64_t\r
220 *               64-bit unsigned integer.\r
221 *\r
222 *       net64_t\r
223 *               64-bit network byte order value.\r
224 *\r
225 *       intn_t\r
226 *               Signed natural sized integer.  32-bit on a 32-bit platform, 64-bit on\r
227 *               a 64-bit platform.\r
228 *\r
229 *       uintn_t\r
230 *               Unsigned natural sized integer.  32-bit on a 32-bit platform, 64-bit on\r
231 *               a 64-bit platform.\r
232 *\r
233 *       boolean_t\r
234 *               integral sized.  Set to TRUE or FALSE and used in logical expressions.\r
235 *\r
236 * NOTES\r
237 *       Pointer types are not defined as these provide no value and can potentially\r
238 *       lead to naming confusion.\r
239 *********/\r
240 \r
241 \r
242 /****d* Component Library: Data Types/cl_status_t\r
243 * NAME\r
244 *       cl_status_t\r
245 *\r
246 * DESCRIPTION\r
247 *       The cl_status_t return types are used by the component library to\r
248 *       provide detailed function return values.\r
249 *\r
250 * SYNOPSIS\r
251 */\r
252 #ifdef CL_KERNEL\r
253 \r
254 typedef enum _cl_status\r
255 {\r
256         CL_SUCCESS                                      = STATUS_SUCCESS,\r
257         CL_ERROR                                                = STATUS_DRIVER_INTERNAL_ERROR,\r
258         CL_INVALID_STATE                                = STATUS_INVALID_DEVICE_STATE,\r
259         CL_INVALID_OPERATION                    = STATUS_NOT_SUPPORTED,\r
260         CL_INVALID_SETTING                      = STATUS_INVALID_PARAMETER_MIX,\r
261         CL_INVALID_PARAMETER                    = STATUS_INVALID_PARAMETER,\r
262         CL_INSUFFICIENT_RESOURCES       = STATUS_INSUFFICIENT_RESOURCES,\r
263         CL_INSUFFICIENT_MEMORY          = STATUS_NO_MEMORY,\r
264         CL_INVALID_PERMISSION                   = STATUS_ACCESS_DENIED,\r
265         CL_COMPLETED                                    = STATUS_EVENT_DONE,\r
266         CL_NOT_DONE                                     = STATUS_ABANDONED,\r
267         CL_PENDING                                              = STATUS_PENDING,\r
268         CL_TIMEOUT                                              = STATUS_TIMEOUT,\r
269         CL_CANCELED                                     = STATUS_CANCELLED,\r
270         CL_REJECT                                               = STATUS_REQUEST_NOT_ACCEPTED,\r
271         CL_OVERRUN                                              = STATUS_DATA_OVERRUN,\r
272         CL_NOT_FOUND                                    = STATUS_NOT_FOUND,\r
273         CL_UNAVAILABLE                          = STATUS_DEVICE_NOT_READY,\r
274         CL_BUSY                                         = STATUS_DEVICE_BUSY,\r
275         CL_DISCONNECT                                   = STATUS_LOCAL_DISCONNECT,\r
276         CL_DUPLICATE                                    = STATUS_DUPLICATE_NAME,\r
277         CL_INVALID_REQUEST                      = STATUS_INVALID_DEVICE_REQUEST,\r
278         CL_INVALID_HANDLE                       = STATUS_INVALID_HANDLE,\r
279         CL_CONNECTION_INVALID           = STATUS_CONNECTION_INVALID\r
280 \r
281 } cl_status_t;\r
282 \r
283 #else\r
284 \r
285 typedef enum _cl_status\r
286 {\r
287         CL_SUCCESS = 0,\r
288         CL_ERROR,\r
289         CL_INVALID_STATE,\r
290         CL_INVALID_OPERATION,\r
291         CL_INVALID_SETTING,\r
292         CL_INVALID_PARAMETER,\r
293         CL_INSUFFICIENT_RESOURCES,\r
294         CL_INSUFFICIENT_MEMORY,\r
295         CL_INVALID_PERMISSION,\r
296         CL_COMPLETED,\r
297         CL_NOT_DONE,\r
298         CL_PENDING,\r
299         CL_TIMEOUT,\r
300         CL_CANCELED,\r
301         CL_REJECT,\r
302         CL_OVERRUN,\r
303         CL_NOT_FOUND,\r
304         CL_UNAVAILABLE,\r
305         CL_BUSY,\r
306         CL_DISCONNECT,\r
307         CL_DUPLICATE,\r
308         CL_INVALID_REQUEST,\r
309 \r
310         CL_STATUS_COUNT                 /* should be the last value */\r
311 \r
312 } cl_status_t;\r
313 \r
314 #endif\r
315 \r
316 /*\r
317 * SEE ALSO\r
318 *       Data Types, CL_STATUS_MSG\r
319 *********/\r
320 \r
321 \r
322 #ifdef __cplusplus\r
323 extern "C"\r
324 {\r
325 #endif  /* __cplusplus */\r
326 \r
327 \r
328 #ifndef CL_KERNEL\r
329 /* Status values above converted to text for easier printing. */\r
330 CL_EXPORT const char* cl_status_text[CL_STATUS_COUNT];\r
331 #endif\r
332 \r
333 #ifndef cl_panic\r
334 /****f* Component Library: Error Trapping/cl_panic\r
335 * NAME\r
336 *       cl_panic\r
337 *\r
338 * DESCRIPTION\r
339 *       Halts execution of the current process.  Halts the system if called in\r
340 *       from the kernel.\r
341 *\r
342 * SYNOPSIS\r
343 */\r
344 CL_EXPORT void CL_API\r
345 cl_panic(\r
346         IN      const char* const       message,\r
347         IN      ... );\r
348 /*\r
349 * PARAMETERS\r
350 *       message\r
351 *               [in] ANSI string formatted identically as for a call to the standard C\r
352 *               function printf describing the cause for the panic.\r
353 *\r
354 *       ...\r
355 *               [in] Extra parameters for string formatting, as defined for the\r
356 *               standard C function printf.\r
357 *\r
358 * RETURN VALUE\r
359 *       This function does not return.\r
360 *\r
361 * NOTES\r
362 *       The formatting of the message string is the same as for printf\r
363 *\r
364 *       cl_panic sends the message to the current message logging target.\r
365 *********/\r
366 #endif  /* cl_panic */\r
367 \r
368 \r
369 /****d* Component Library: Data Types/CL_STATUS_MSG\r
370 * NAME\r
371 *       CL_STATUS_MSG\r
372 *\r
373 * DESCRIPTION\r
374 *       The CL_STATUS_MSG macro returns a textual representation of\r
375 *       an cl_status_t code.\r
376 *\r
377 * SYNOPSIS\r
378 *       const char*\r
379 *       CL_STATUS_MSG(\r
380 *               IN cl_status_t errcode );\r
381 *\r
382 * PARAMETERS\r
383 *       errcode\r
384 *               [in] cl_status_t code for which to return a text representation.\r
385 *\r
386 * RETURN VALUE\r
387 *       Pointer to a string containing a textual representation of the errcode\r
388 *       parameter.\r
389 *\r
390 * NOTES\r
391 *       This function performs boundary checking on the cl_status_t value,\r
392 *       masking off the upper 24-bits. If the value is out of bounds, the string\r
393 *       "invalid status code" is returned.\r
394 *\r
395 * SEE ALSO\r
396 *       cl_status_t\r
397 *********/\r
398 #ifndef CL_KERNEL\r
399 #define CL_STATUS_MSG( errcode ) \\r
400         ((errcode < CL_STATUS_COUNT)?cl_status_text[errcode]:"invalid status code")\r
401 #endif  \r
402 \r
403 \r
404 #if !defined( FALSE )\r
405 #define FALSE   0\r
406 #endif  /* !defined( TRUE ) */\r
407 \r
408 \r
409 #if !defined( TRUE )\r
410 #define TRUE    (!FALSE)\r
411 #endif  /* !defined( TRUE ) */\r
412 \r
413 \r
414 /****d* Component Library: Unreferenced Parameters/UNUSED_PARAM\r
415 * NAME\r
416 *       UNUSED_PARAM\r
417 *\r
418 * DESCRIPTION\r
419 *       The UNUSED_PARAM macro can be used to eliminates compiler warnings related\r
420 *       to intentionally unused formal parameters in function implementations.\r
421 *\r
422 * SYNOPSIS\r
423 *       UNUSED_PARAM( P )\r
424 *\r
425 * EXAMPLE\r
426 *       void my_func( int32_t value )\r
427 *       {\r
428 *               UNUSED_PARAM( value );\r
429 *       }\r
430 *********/\r
431 \r
432 \r
433 /****d* Component Library/Object States\r
434 * NAME\r
435 *       Object States\r
436 *\r
437 * DESCRIPTION\r
438 *       The object states enumerated type defines the valid states of components.\r
439 *\r
440 * SYNOPSIS\r
441 */\r
442 typedef enum _cl_state\r
443 {\r
444         CL_UNINITIALIZED = 1,\r
445         CL_INITIALIZED,\r
446         CL_DESTROYING,\r
447         CL_DESTROYED\r
448 \r
449 } cl_state_t;\r
450 /*\r
451 * VALUES\r
452 *       CL_UNINITIALIZED\r
453 *               Indicates that initialization was not invoked successfully.\r
454 *\r
455 *       CL_INITIALIZED\r
456 *               Indicates initialization was successful.\r
457 *\r
458 *       CL_DESTROYING\r
459 *               Indicates that the object is undergoing destruction.\r
460 *\r
461 *       CL_DESTROYED\r
462 *               Indicates that the object's destructor has already been called.  Most\r
463 *               objects set their final state to CL_DESTROYED before freeing the\r
464 *               memory associated with the object.\r
465 *********/\r
466 \r
467 \r
468 /****d* Component Library: Object States/cl_is_state_valid\r
469 * NAME\r
470 *       cl_is_state_valid\r
471 *\r
472 * DESCRIPTION\r
473 *       The cl_is_state_valid function returns whether a state has a valid value.\r
474 *\r
475 * SYNOPSIS\r
476 */\r
477 CL_INLINE boolean_t CL_API\r
478 cl_is_state_valid(\r
479         IN      const cl_state_t        state )\r
480 {\r
481         return( (state == CL_UNINITIALIZED) || (state == CL_INITIALIZED) ||\r
482                 (state == CL_DESTROYING) || (state == CL_DESTROYED) );\r
483 }\r
484 /*\r
485 * PARAMETERS\r
486 *       state\r
487 *               State whose value to validate.\r
488 *\r
489 * RETURN VALUES\r
490 *       TRUE if the specified state has a valid value.\r
491 *\r
492 *       FALSE otherwise.\r
493 *\r
494 * NOTES\r
495 *       This function is used in debug builds to check for valid states.  If an\r
496 *       uninitialized object is passed, the memory for the state may cause the\r
497 *       state to have an invalid value.\r
498 *\r
499 * SEE ALSO\r
500 *       Object States\r
501 *********/\r
502 \r
503 \r
504 #ifdef __cplusplus\r
505 }\r
506 #endif  /* __cplusplus */\r
507 \r
508 \r
509 #endif /* _DATA_TYPES_H_ */\r