[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_memory.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  *      Declaration of generic memory allocation calls.\r
37  *\r
38  * Environment:\r
39  *      All\r
40  */\r
41 \r
42 \r
43 #ifndef _CL_MEMORY_H_\r
44 #define _CL_MEMORY_H_\r
45 \r
46 \r
47 #include <complib/cl_types.h>\r
48 #include <complib/cl_memory_osd.h>\r
49 \r
50 \r
51 /****h* Public/Memory Management\r
52 * NAME\r
53 *       Memory Management\r
54 *\r
55 * DESCRIPTION\r
56 *       The memory management functionality provides memory manipulation\r
57 *       functions as well as powerful debugging tools.\r
58 *\r
59 *       The Allocation Tracking functionality provides a means for tracking memory\r
60 *       allocations in order to detect memory leaks.\r
61 *\r
62 *       Memory allocation tracking stores the file name and line number where\r
63 *       allocations occur. Gathering this information does have an adverse impact\r
64 *       on performance, and memory tracking should therefore not be enabled in\r
65 *       release builds of software.\r
66 *\r
67 *       Memory tracking is compiled into the debug version of the library,\r
68 *       and can be enabled for the release version as well. To Enable memory\r
69 *       tracking in a release build of the public layer, users should define\r
70 *       the MEM_TRACK_ON keyword for compilation.\r
71 *********/\r
72 \r
73 \r
74 #ifdef __cplusplus\r
75 extern "C"\r
76 {\r
77 #endif\r
78 \r
79 \r
80 /****i* Component Library: Memory Management/__cl_mem_track\r
81 * NAME\r
82 *       __cl_mem_track\r
83 *\r
84 * DESCRIPTION\r
85 *       The __cl_mem_track function enables or disables memory allocation tracking.\r
86 *\r
87 * SYNOPSIS\r
88 */\r
89 CL_EXPORT void CL_API\r
90 __cl_mem_track(\r
91         IN      const boolean_t start );\r
92 /*\r
93 * PARAMETERS\r
94 *       start\r
95 *               [in] Specifies whether to start or stop memory tracking.\r
96 *\r
97 * RETURN VALUE\r
98 *       This function does not return a value.\r
99 *\r
100 * NOTES\r
101 *       This function performs all necessary initialization for tracking\r
102 *       allocations.  Users should never call this function, as it is called by\r
103 *       the component library framework.\r
104 *\r
105 *       If the Start parameter is set to TRUE, the function starts tracking memory\r
106 *       usage if not already started. When set to FALSE, memory tracking is stoped\r
107 *       and all remaining allocations are displayed to the applicable debugger, if\r
108 *       any.\r
109 *\r
110 *       Starting memory tracking when it is already started has no effect.\r
111 *       Likewise, stoping memory tracking when it is already stopped has no effect.\r
112 *\r
113 * SEE ALSO\r
114 *       Memory Management, cl_mem_display\r
115 **********/\r
116 \r
117 \r
118 /****f* Component Library: Memory Management/cl_mem_display\r
119 * NAME\r
120 *       cl_mem_display\r
121 *\r
122 * DESCRIPTION\r
123 *       The cl_mem_display function displays all tracked memory allocations to\r
124 *       the applicable debugger.\r
125 *\r
126 * SYNOPSIS\r
127 */\r
128 CL_EXPORT void CL_API\r
129 cl_mem_display( void );\r
130 /*\r
131 * RETURN VALUE\r
132 *       This function does not return a value.\r
133 *\r
134 * NOTES\r
135 *       Each tracked memory allocation is displayed along with the file name and\r
136 *       line number that allocated it.\r
137 *\r
138 *       Output is sent to the platform's debugging target, which may be the\r
139 *       system log file.\r
140 *\r
141 * SEE ALSO\r
142 *       Memory Management\r
143 **********/\r
144 \r
145 \r
146 /****i* Component Library: Memory Management/__cl_malloc_trk\r
147 * NAME\r
148 *       __cl_malloc_trk\r
149 *\r
150 * DESCRIPTION\r
151 *       The __cl_malloc_trk function allocates and tracks a block of memory.\r
152 *\r
153 * SYNOPSIS\r
154 */\r
155 CL_EXPORT void* CL_API\r
156 __cl_malloc_trk(\r
157         IN      const char* const       p_file_name,\r
158         IN      const int32_t           line_num,\r
159         IN      const size_t            bytes,\r
160         IN      const boolean_t         pageable );\r
161 /*\r
162 * PARAMETERS\r
163 *       p_file_name\r
164 *               [in] Name of the source file initiating the allocation.\r
165 *\r
166 *       line_num\r
167 *               [in] Line number in the specified file where the allocation is\r
168 *               initiated\r
169 *\r
170 *       size\r
171 *               [in] Size of the requested allocation.\r
172 *\r
173 *       pageable\r
174 *               [in] On operating systems that support pageable vs. non pageable\r
175 *               memory in the kernel, set to TRUE to allocate memory from paged pool.\r
176 *\r
177 * RETURN VALUES\r
178 *       Pointer to allocated memory if successful.\r
179 *\r
180 *       NULL otherwise.\r
181 *\r
182 * NOTES\r
183 *       Allocated memory follows alignment rules specific to the different\r
184 *       environments.\r
185 *       This function is should not be called directly.  The cl_malloc macro will\r
186 *       redirect users to this function when memory tracking is enabled.\r
187 *\r
188 * SEE ALSO\r
189 *       Memory Management, __cl_malloc_ntrk, __cl_zalloc_trk, __cl_free_trk\r
190 **********/\r
191 \r
192 \r
193 /****i* Component Library: Memory Management/__cl_zalloc_trk\r
194 * NAME\r
195 *       __cl_zalloc_trk\r
196 *\r
197 * DESCRIPTION\r
198 *       The __cl_zalloc_trk function allocates and tracks a block of memory\r
199 *       initialized to zero.\r
200 *\r
201 * SYNOPSIS\r
202 */\r
203 CL_EXPORT void* CL_API\r
204 __cl_zalloc_trk(\r
205         IN      const char* const       p_file_name,\r
206         IN      const int32_t           line_num,\r
207         IN      const size_t            bytes,\r
208         IN      const boolean_t         pageable );\r
209 /*\r
210 * PARAMETERS\r
211 *       p_file_name\r
212 *               [in] Name of the source file initiating the allocation.\r
213 *\r
214 *       line_num\r
215 *               [in] Line number in the specified file where the allocation is\r
216 *               initiated\r
217 *\r
218 *       size\r
219 *               [in] Size of the requested allocation.\r
220 *\r
221 *       pageable\r
222 *               [in] On operating systems that support pageable vs. non pageable\r
223 *               memory in the kernel, set to TRUE to allocate memory from paged pool.\r
224 *\r
225 * RETURN VALUES\r
226 *       Pointer to allocated memory if successful.\r
227 *\r
228 *       NULL otherwise.\r
229 *\r
230 * NOTES\r
231 *       Allocated memory follows alignment rules specific to the different\r
232 *       environments.\r
233 *       This function should not be called directly.  The cl_zalloc macro will\r
234 *       redirect users to this function when memory tracking is enabled.\r
235 *\r
236 * SEE ALSO\r
237 *       Memory Management, __cl_zalloc_ntrk, __cl_malloc_trk, __cl_free_trk\r
238 **********/\r
239 \r
240 \r
241 /****i* Component Library: Memory Management/__cl_malloc_ntrk\r
242 * NAME\r
243 *       __cl_malloc_ntrk\r
244 *\r
245 * DESCRIPTION\r
246 *       The __cl_malloc_ntrk function allocates a block of memory.\r
247 *\r
248 * SYNOPSIS\r
249 */\r
250 CL_EXPORT void* CL_API\r
251 __cl_malloc_ntrk(\r
252         IN      const size_t            size,\r
253         IN      const boolean_t         pageable );\r
254 /*\r
255 * PARAMETERS\r
256 *       size\r
257 *               [in] Size of the requested allocation.\r
258 *\r
259 *       pageable\r
260 *               [in] On operating systems that support pageable vs. non pageable\r
261 *               memory in the kernel, set to TRUE to allocate memory from paged pool.\r
262 *\r
263 * RETURN VALUES\r
264 *       Pointer to allocated memory if successful.\r
265 *\r
266 *       NULL otherwise.\r
267 *\r
268 * NOTES\r
269 *       Allocated memory follows alignment rules specific to the different\r
270 *       environments.\r
271 *       This function is should not be called directly.  The cl_malloc macro will\r
272 *       redirect users to this function when memory tracking is not enabled.\r
273 *\r
274 * SEE ALSO\r
275 *       Memory Management, __cl_malloc_trk, __cl_zalloc_ntrk, __cl_free_ntrk\r
276 **********/\r
277 \r
278 \r
279 /****i* Component Library: Memory Management/__cl_zalloc_ntrk\r
280 * NAME\r
281 *       __cl_zalloc_ntrk\r
282 *\r
283 * DESCRIPTION\r
284 *       The __cl_zalloc_ntrk function allocates a block of memory\r
285 *       initialized to zero.\r
286 *\r
287 * SYNOPSIS\r
288 */\r
289 CL_EXPORT void* CL_API\r
290 __cl_zalloc_ntrk(\r
291         IN      const size_t            bytes,\r
292         IN      const boolean_t         pageable );\r
293 /*\r
294 * PARAMETERS\r
295 *       size\r
296 *               [in] Size of the requested allocation.\r
297 *\r
298 *       pageable\r
299 *               [in] On operating systems that support pageable vs. non pageable\r
300 *               memory in the kernel, set to TRUE to allocate memory from paged pool.\r
301 *\r
302 * RETURN VALUES\r
303 *       Pointer to allocated memory if successful.\r
304 *\r
305 *       NULL otherwise.\r
306 *\r
307 * NOTES\r
308 *       Allocated memory follows alignment rules specific to the different\r
309 *       environments.\r
310 *       This function should not be called directly.  The cl_zalloc macro will\r
311 *       redirect users to this function when memory tracking is not enabled.\r
312 *\r
313 * SEE ALSO\r
314 *       Memory Management, __cl_zalloc_trk, __cl_malloc_ntrk, __cl_free_ntrk\r
315 **********/\r
316 \r
317 \r
318 /****i* Component Library: Memory Management/__cl_free_trk\r
319 * NAME\r
320 *       __cl_free_trk\r
321 *\r
322 * DESCRIPTION\r
323 *       The __cl_free_trk function deallocates a block of tracked memory.\r
324 *\r
325 * SYNOPSIS\r
326 */\r
327 CL_EXPORT void CL_API\r
328 __cl_free_trk(\r
329         IN      void* const     p_memory );\r
330 /*\r
331 * PARAMETERS\r
332 *       p_memory\r
333 *               [in] Pointer to a memory block.\r
334 *\r
335 * RETURN VALUE\r
336 *       This function does not return a value.\r
337 *\r
338 * NOTES\r
339 *       The p_memory parameter is the pointer returned by a previous call to\r
340 *       __cl_malloc_trk, or __cl_zalloc_trk.\r
341 *\r
342 *       __cl_free_trk has no effect if p_memory is NULL.\r
343 *\r
344 *       This function should not be called directly.  The cl_free macro will\r
345 *       redirect users to this function when memory tracking is enabled.\r
346 *\r
347 * SEE ALSO\r
348 *       Memory Management, __cl_free_ntrk, __cl_malloc_trk, __cl_zalloc_trk\r
349 **********/\r
350 \r
351 \r
352 /****i* Component Library: Memory Management/__cl_free_ntrk\r
353 * NAME\r
354 *       __cl_free_ntrk\r
355 *\r
356 * DESCRIPTION\r
357 *       The __cl_free_ntrk function deallocates a block of memory.\r
358 *\r
359 * SYNOPSIS\r
360 */\r
361 CL_EXPORT void CL_API\r
362 __cl_free_ntrk(\r
363         IN      void* const     p_memory );\r
364 /*\r
365 * PARAMETERS\r
366 *       p_memory\r
367 *               [in] Pointer to a memory block.\r
368 *\r
369 * RETURN VALUE\r
370 *       This function does not return a value.\r
371 *\r
372 * NOTES\r
373 *       The p_memory parameter is the pointer returned by a previous call to\r
374 *       __cl_malloc_ntrk, or __cl_zalloc_ntrk.\r
375 *\r
376 *       __cl_free_ntrk has no effect if p_memory is NULL.\r
377 *\r
378 *       This function should not be called directly.  The cl_free macro will\r
379 *       redirect users to this function when memory tracking is not enabled.\r
380 *\r
381 * SEE ALSO\r
382 *       Memory Management, __cl_free_ntrk, __cl_malloc_trk, __cl_zalloc_trk\r
383 **********/\r
384 \r
385 \r
386 /****f* Component Library: Memory Management/cl_malloc\r
387 * NAME\r
388 *       cl_malloc\r
389 *\r
390 * DESCRIPTION\r
391 *       The cl_malloc function allocates a block of memory.\r
392 *\r
393 * SYNOPSIS\r
394 */\r
395 void*\r
396 cl_malloc(\r
397         IN      const size_t    size );\r
398 /*\r
399 * PARAMETERS\r
400 *       size\r
401 *               [in] Size of the requested allocation.\r
402 *\r
403 * RETURN VALUES\r
404 *       Pointer to allocated memory if successful.\r
405 *\r
406 *       NULL otherwise.\r
407 *\r
408 * NOTES\r
409 *       Allocated memory follows alignment rules specific to the different\r
410 *       environments.\r
411 *\r
412 * SEE ALSO\r
413 *       Memory Management, cl_free, cl_zalloc, cl_palloc, cl_pzalloc,\r
414 *       cl_memset, cl_memclr, cl_memcpy, cl_memcmp\r
415 **********/\r
416 \r
417 \r
418 /****f* Component Library: Memory Management/cl_zalloc\r
419 * NAME\r
420 *       cl_zalloc\r
421 *\r
422 * DESCRIPTION\r
423 *       The cl_zalloc function allocates a block of memory initialized to zero.\r
424 *\r
425 * SYNOPSIS\r
426 */\r
427 void*\r
428 cl_zalloc(\r
429         IN      const size_t    size );\r
430 /*\r
431 * PARAMETERS\r
432 *       size\r
433 *               [in] Size of the requested allocation.\r
434 *\r
435 * RETURN VALUES\r
436 *       Pointer to allocated memory if successful.\r
437 *\r
438 *       NULL otherwise.\r
439 *\r
440 * NOTES\r
441 *       Allocated memory follows alignment rules specific to the different\r
442 *       environments.\r
443 *\r
444 * SEE ALSO\r
445 *       Memory Management, cl_free, cl_malloc, cl_palloc, cl_pzalloc,\r
446 *       cl_memset, cl_memclr, cl_memcpy, cl_memcmp\r
447 **********/\r
448 \r
449 \r
450 /****f* Component Library: Memory Management/cl_palloc\r
451 * NAME\r
452 *       cl_palloc\r
453 *\r
454 * DESCRIPTION\r
455 *       The cl_palloc function allocates a block of memory from paged pool if the\r
456 *       operating system supports it.  If the operating system does not distinguish\r
457 *       between pool types, cl_palloc is identical to cl_malloc.\r
458 *\r
459 * SYNOPSIS\r
460 */\r
461 void*\r
462 cl_palloc(\r
463         IN      const size_t    size );\r
464 /*\r
465 * PARAMETERS\r
466 *       size\r
467 *               [in] Size of the requested allocation.\r
468 *\r
469 * RETURN VALUES\r
470 *       Pointer to allocated memory if successful.\r
471 *\r
472 *       NULL otherwise.\r
473 *\r
474 * NOTES\r
475 *       Allocated memory follows alignment rules specific to the different\r
476 *       environments.\r
477 *\r
478 * SEE ALSO\r
479 *       Memory Management, cl_free, cl_malloc, cl_zalloc, cl_pzalloc,\r
480 *       cl_memset, cl_memclr, cl_memcpy, cl_memcmp\r
481 **********/\r
482 \r
483 \r
484 /****f* Component Library: Memory Management/cl_pzalloc\r
485 * NAME\r
486 *       cl_pzalloc\r
487 *\r
488 * DESCRIPTION\r
489 *       The cl_pzalloc function allocates a block of memory from paged pool if the\r
490 *       operating system supports it and initializes it to zero.  If the operating\r
491 *       system does not distinguish between pool types, cl_pzalloc is identical\r
492 *       to cl_zalloc.\r
493 *\r
494 * SYNOPSIS\r
495 */\r
496 void*\r
497 cl_pzalloc(\r
498         IN      const size_t    size );\r
499 /*\r
500 * PARAMETERS\r
501 *       size\r
502 *               [in] Size of the requested allocation.\r
503 *\r
504 * RETURN VALUES\r
505 *       Pointer to allocated memory if successful.\r
506 *\r
507 *       NULL otherwise.\r
508 *\r
509 * NOTES\r
510 *       Allocated memory follows alignment rules specific to the different\r
511 *       environments.\r
512 *\r
513 * SEE ALSO\r
514 *       Memory Management, cl_free, cl_malloc, cl_zalloc, cl_palloc,\r
515 *       cl_memset, cl_memclr, cl_memcpy, cl_memcmp\r
516 **********/\r
517 \r
518 \r
519 /****f* Component Library: Memory Management/cl_free\r
520 * NAME\r
521 *       cl_free\r
522 *\r
523 * DESCRIPTION\r
524 *       The cl_free function deallocates a block of memory.\r
525 *\r
526 * SYNOPSIS\r
527 */\r
528 void\r
529 cl_free(\r
530         IN      void* const     p_memory );\r
531 /*\r
532 * PARAMETERS\r
533 *       p_memory\r
534 *               [in] Pointer to a memory block.\r
535 *\r
536 * RETURN VALUE\r
537 *       This function does not return a value.\r
538 *\r
539 * NOTES\r
540 *       The p_memory parameter is the pointer returned by a previous call to\r
541 *       cl_malloc, or cl_zalloc.\r
542 *\r
543 *       cl_free has no effect if p_memory is NULL.\r
544 *\r
545 * SEE ALSO\r
546 *       Memory Management, cl_alloc, cl_zalloc\r
547 **********/\r
548 \r
549 \r
550 /****f* Component Library: Memory Management/cl_memset\r
551 * NAME\r
552 *       cl_memset\r
553 *\r
554 * DESCRIPTION\r
555 *       The cl_memset function sets every byte in a memory range to a given value.\r
556 *\r
557 * SYNOPSIS\r
558 */\r
559 CL_EXPORT void CL_API\r
560 cl_memset(\r
561         IN      void* const             p_memory,\r
562         IN      const uint8_t   fill,\r
563         IN      const size_t    count );\r
564 /*\r
565 * PARAMETERS\r
566 *       p_memory\r
567 *               [in] Pointer to a memory block.\r
568 *\r
569 *       fill\r
570 *               [in] Byte value with which to fill the memory.\r
571 *\r
572 *       count\r
573 *               [in] Number of bytes to set.\r
574 *\r
575 * RETURN VALUE\r
576 *       This function does not return a value.\r
577 *\r
578 * SEE ALSO\r
579 *       Memory Management, cl_memclr, cl_memcpy, cl_memcmp\r
580 **********/\r
581 \r
582 \r
583 #ifndef _CL_MEMCLR_DEFINED_\r
584 /****f* Component Library: Memory Management/cl_memclr\r
585 * NAME\r
586 *       cl_memclr\r
587 *\r
588 * DESCRIPTION\r
589 *       The cl_memclr function sets every byte in a memory range to zero.\r
590 *\r
591 * SYNOPSIS\r
592 */\r
593 CL_INLINE void CL_API\r
594 cl_memclr(\r
595         IN      void* const             p_memory,\r
596         IN      const size_t    count )\r
597 {\r
598         cl_memset( p_memory, 0, count );\r
599 }\r
600 /*\r
601 * PARAMETERS\r
602 *       p_memory\r
603 *               [in] Pointer to a memory block.\r
604 *\r
605 *       count\r
606 *               [in] Number of bytes to set.\r
607 *\r
608 * RETURN VALUE\r
609 *       This function does not return a value.\r
610 *\r
611 * SEE ALSO\r
612 *       Memory Management, cl_memset, cl_memcpy, cl_memcmp\r
613 **********/\r
614 #endif\r
615 \r
616 \r
617 /****f* Component Library: Memory Management/cl_memcpy\r
618 * NAME\r
619 *       cl_memcpy\r
620 *\r
621 * DESCRIPTION\r
622 *       The cl_memcpy function copies a given number of bytes from\r
623 *       one buffer to another.\r
624 *\r
625 * SYNOPSIS\r
626 */\r
627 CL_EXPORT void* CL_API\r
628 cl_memcpy(\r
629         IN      void* const                     p_dest,\r
630         IN      const void* const       p_src,\r
631         IN      const size_t            count );\r
632 /*\r
633 * PARAMETERS\r
634 *       p_dest\r
635 *               [in] Pointer to the buffer being copied to.\r
636 *\r
637 *       p_src\r
638 *               [in] Pointer to the buffer being copied from.\r
639 *\r
640 *       count\r
641 *               [in] Number of bytes to copy from the source buffer to the\r
642 *               destination buffer.\r
643 *\r
644 * RETURN VALUE\r
645 *       Returns a pointer to the destination buffer.\r
646 *\r
647 * SEE ALSO\r
648 *       Memory Management, cl_memset, cl_memclr, cl_memcmp\r
649 **********/\r
650 \r
651 \r
652 /****f* Component Library: Memory Management/cl_memcmp\r
653 * NAME\r
654 *       cl_memcmp\r
655 *\r
656 * DESCRIPTION\r
657 *       The cl_memcmp function compares two memory buffers.\r
658 *\r
659 * SYNOPSIS\r
660 */\r
661 CL_EXPORT int32_t CL_API\r
662 cl_memcmp(\r
663         IN      const void* const       p_mem,\r
664         IN      const void* const       p_ref,\r
665         IN      const size_t            count );\r
666 /*\r
667 * PARAMETERS\r
668 *       p_mem\r
669 *               [in] Pointer to a memory block being compared.\r
670 *\r
671 *       p_ref\r
672 *               [in] Pointer to the reference memory block to compare against.\r
673 *\r
674 *       count\r
675 *               [in] Number of bytes to compare.\r
676 *\r
677 * RETURN VALUES\r
678 *       Returns less than zero if p_mem is less than p_ref.\r
679 *\r
680 *       Returns greater than zero if p_mem is greater than p_ref.\r
681 *\r
682 *       Returns zero if the two memory regions are the identical.\r
683 *\r
684 * SEE ALSO\r
685 *       Memory Management, cl_memset, cl_memclr, cl_memcpy\r
686 **********/\r
687 \r
688 \r
689 #ifdef CL_KERNEL\r
690 \r
691 /****f* Component Library: Memory Management/cl_get_pagesize\r
692 * NAME\r
693 *       cl_get_pagesize\r
694 *\r
695 * DESCRIPTION\r
696 *       Returns the number of bytes in a OS defined page.\r
697 *\r
698 * SYNOPSIS\r
699 */\r
700 CL_EXPORT uint32_t CL_API\r
701 cl_get_pagesize( void );\r
702 /*\r
703 * PARAMETERS\r
704 *       NONE\r
705 *\r
706 * RETURN VALUES\r
707 *       Returns the number of bytes in a page as defined by the Operating\r
708 *       System.\r
709 *\r
710 * SEE ALSO\r
711 *       Memory Management\r
712 **********/\r
713 \r
714 \r
715 /****f* Component Library: Memory Management/cl_get_physaddr\r
716 * NAME\r
717 *       cl_get_physaddr\r
718 *\r
719 * DESCRIPTION\r
720 *       Returns the Physical address for a kernel virtual address.\r
721 *\r
722 * SYNOPSIS\r
723 */\r
724 CL_EXPORT uint64_t CL_API\r
725 cl_get_physaddr(\r
726         IN      void *vaddr );\r
727 /*\r
728 * PARAMETERS\r
729 *       p_addr\r
730 *               [in] Pointer to virtual to which the physical address is required.\r
731 *\r
732 * RETURN VALUES\r
733 *       Returns the physical address for a virtual address.\r
734 *\r
735 * NOTES\r
736 *       This call is only available in kernel mode.\r
737 *\r
738 * SEE ALSO\r
739 *       Memory Management\r
740 **********/\r
741 \r
742 \r
743 /****f* Component Library: Memory Management/cl_check_for_read\r
744 * NAME\r
745 *       cl_check_for_read\r
746 *\r
747 * DESCRIPTION\r
748 *       Checks a user-mode virtual address for read access.\r
749 *\r
750 * SYNOPSIS\r
751 */\r
752 CL_EXPORT cl_status_t CL_API\r
753 cl_check_for_read(\r
754         IN      const void* const       vaddr,\r
755         IN      const size_t            count );\r
756 /*\r
757 * PARAMETERS\r
758 *       vaddr\r
759 *               [in] Virtual address to check for read access.\r
760 *\r
761 *       count\r
762 *               [in] Number of bytes of the buffer at the specified address\r
763 *               to validate.\r
764 *\r
765 * RETURN VALUES\r
766 *       CL_SUCCESS if the virtual address is valid for a read of the specified\r
767 *       size.\r
768 *\r
769 *       CL_INVALID_PERMISSION if the virtual address or the size is not valid.\r
770 *\r
771 * NOTES\r
772 *       This call is only available in the kernel.  The buffer can only be accessed\r
773 *       in the context of the application thread (i.e. in the path of an IOCTL\r
774 *       request).  Callers cannot be holding a spinlock when calling this function.\r
775 *\r
776 * SEE ALSO\r
777 *       Memory Management, cl_check_for_write, cl_copy_to_user, cl_copy_from_user\r
778 *********/\r
779 \r
780 \r
781 /****f* Component Library: Memory Management/cl_check_for_write\r
782 * NAME\r
783 *       cl_check_for_write\r
784 *\r
785 * DESCRIPTION\r
786 *       Checks a user-mode virtual address for write access.\r
787 *\r
788 * SYNOPSIS\r
789 */\r
790 CL_EXPORT cl_status_t CL_API\r
791 cl_check_for_write(\r
792         IN      void* const             vaddr,\r
793         IN      const size_t    count );\r
794 /*\r
795 * PARAMETERS\r
796 *       vaddr\r
797 *               [in] Virtual address to check for write access.\r
798 *\r
799 *       count\r
800 *               [in] Number of bytes of the buffer at the specified\r
801 *               address to validate.\r
802 *\r
803 * RETURN VALUES\r
804 *       CL_SUCCESS if the virtual address is valid for a write of the specified\r
805 *       size.\r
806 *\r
807 *       CL_INVALID_PERMISSION if the virtual address or the size is not valid.\r
808 *\r
809 * NOTES\r
810 *       This call is only available in the kernel.  The buffer can only be accessed\r
811 *       in the context of the application thread (i.e. in the path of an IOCTL\r
812 *       request).  Callers cannot be holding a spinlock when calling this function.\r
813 *\r
814 * SEE ALSO\r
815 *       Memory Management, cl_check_for_read, cl_copy_to_user, cl_copy_from_user\r
816 *********/\r
817 \r
818 \r
819 /****f* Component Library: Memory Management/cl_copy_to_user\r
820 * NAME\r
821 *       cl_copy_to_user\r
822 *\r
823 * DESCRIPTION\r
824 *       Copies data into a user-mode buffer, performing access checks.\r
825 *\r
826 * SYNOPSIS\r
827 */\r
828 CL_EXPORT cl_status_t CL_API\r
829 cl_copy_to_user(\r
830         IN      void* const                     p_dest,\r
831         IN      const void* const       p_src,\r
832         IN      const size_t            count );\r
833 /*\r
834 * PARAMETERS\r
835 *       p_dest\r
836 *               [in] User-mode virtual address to which to copy data.\r
837 *\r
838 *       p_src\r
839 *               [in] Pointer to the buffer being copied from.\r
840 *\r
841 *       count\r
842 *               [in] Number of bytes to copy from the source buffer to the\r
843 *               destination buffer.\r
844 *\r
845 * RETURN VALUES\r
846 *       CL_SUCCESS if the user-mode buffer virtual address is valid as the\r
847 *       destination of the copy.\r
848 *\r
849 *       CL_INVALID_PERMISSION if the virtual address or the count is not valid.\r
850 *\r
851 * NOTES\r
852 *       This call is only available in the kernel.  The buffer can only be accessed\r
853 *       in the context of the application thread (i.e. in the path of an IOCTL\r
854 *       request).  Callers cannot be holding a spinlock when calling this function.\r
855 *\r
856 * SEE ALSO\r
857 *       Memory Management, cl_check_for_read, cl_check_for_write, cl_copy_from_user\r
858 *********/\r
859 \r
860 \r
861 /****f* Component Library: Memory Management/cl_copy_from_user\r
862 * NAME\r
863 *       cl_copy_from_user\r
864 *\r
865 * DESCRIPTION\r
866 *       Copies data from a user-mode buffer, performing access checks.\r
867 *\r
868 * SYNOPSIS\r
869 */\r
870 CL_EXPORT cl_status_t CL_API\r
871 cl_copy_from_user(\r
872         IN      void* const                     p_dest,\r
873         IN      const void* const       p_src,\r
874         IN      const size_t            count );\r
875 /*\r
876 * PARAMETERS\r
877 *       p_dest\r
878 *               [in] Pointer to the buffer being copied to.\r
879 *\r
880 *       p_src\r
881 *               [in] User-mode virtual address from which to copy data.\r
882 *\r
883 *       count\r
884 *               [in] Number of bytes to copy from the source buffer to the\r
885 *               destination buffer.\r
886 *\r
887 * RETURN VALUES\r
888 *       CL_SUCCESS if the user-mode buffer virtual address is valid as the\r
889 *       source of the copy.\r
890 *\r
891 *       CL_INVALID_PERMISSION if the virtual address or the count is not valid.\r
892 *\r
893 * NOTES\r
894 *       This call is only available in the kernel.  The buffer can only be accessed\r
895 *       in the context of the application thread (i.e. in the path of an IOCTL\r
896 *       request).  Callers cannot be holding a spinlock when calling this function.\r
897 *\r
898 * SEE ALSO\r
899 *       Memory Management, cl_check_for_read, cl_check_for_write, cl_copy_to_user\r
900 *********/\r
901 \r
902 #endif  /* CL_KERNEL */\r
903 \r
904 #if defined( CL_NO_TRACK_MEM ) && defined( CL_TRACK_MEM )\r
905         #error Conflict: Cannot define both CL_NO_TRACK_MEM and CL_TRACK_MEM.\r
906 #endif\r
907 \r
908 /*\r
909  * Turn on memory allocation tracking in debug builds if not explicitly\r
910  * disabled or already turned on.\r
911  */\r
912 #if defined( _DEBUG_ ) && \\r
913         !defined( CL_NO_TRACK_MEM ) && \\r
914         !defined( CL_TRACK_MEM )\r
915         #define CL_TRACK_MEM\r
916 #endif\r
917 \r
918 \r
919 /*\r
920  * Define allocation macro.\r
921  */\r
922 #if defined( CL_TRACK_MEM )\r
923 \r
924 #define cl_malloc( a )  \\r
925         __cl_malloc_trk( __FILE__, __LINE__, a, FALSE )\r
926 \r
927 #define cl_zalloc( a )  \\r
928         __cl_zalloc_trk( __FILE__, __LINE__, a, FALSE )\r
929 \r
930 #define cl_palloc( a )  \\r
931         __cl_malloc_trk( __FILE__, __LINE__, a, TRUE )\r
932 \r
933 #define cl_pzalloc( a ) \\r
934         __cl_zalloc_trk( __FILE__, __LINE__, a, TRUE )\r
935 \r
936 #define cl_free( a )    \\r
937         __cl_free_trk( a )\r
938 \r
939 #else   /* !defined( CL_TRACK_MEM ) */\r
940 \r
941 #define cl_malloc( a )  \\r
942         __cl_malloc_ntrk( a, FALSE )\r
943 \r
944 #define cl_zalloc( a )  \\r
945         __cl_zalloc_ntrk( a, FALSE )\r
946 \r
947 #define cl_palloc( a )  \\r
948         __cl_malloc_ntrk( a, TRUE )\r
949 \r
950 #define cl_pzalloc( a ) \\r
951         __cl_zalloc_ntrk( a, TRUE )\r
952 \r
953 #define cl_free( a )    \\r
954         __cl_free_ntrk( a )\r
955 \r
956 #endif  /* defined( CL_TRACK_MEM ) */\r
957 \r
958 \r
959 #ifdef __cplusplus\r
960 }       /* extern "C" */\r
961 #endif\r
962 \r
963 #endif /* _CL_MEMORY_H_ */\r