Generated from ./inc/complib/cl_memory.h with ROBODoc v4.99.17 on Sun Mar 04 2007 18:17:51

[Modules] Public/Memory Management

[top][index]

NAME

       Memory Management

DESCRIPTION

       The memory management functionality provides memory manipulation
       functions as well as powerful debugging tools.

       The Allocation Tracking functionality provides a means for tracking memory
       allocations in order to detect memory leaks.

       Memory allocation tracking stores the file name and line number where
       allocations occur. Gathering this information does have an adverse impact
       on performance, and memory tracking should therefore not be enabled in
       release builds of software.

       Memory tracking is compiled into the debug version of the library,
       and can be enabled for the release version as well. To Enable memory
       tracking in a release build of the public layer, users should define
       the MEM_TRACK_ON keyword for compilation.

[Functions] Component Library: Memory Management/cl_check_for_read

[top][index]

NAME

       cl_check_for_read

DESCRIPTION

       Checks a user-mode virtual address for read access.

SYNOPSIS

CL_EXPORT cl_status_t CL_API
cl_check_for_read(
        IN      const void* const       vaddr,
        IN      const size_t            count );

PARAMETERS

       vaddr
               [in] Virtual address to check for read access.

       count
               [in] Number of bytes of the buffer at the specified address
               to validate.

 RETURN VALUES
       CL_SUCCESS if the virtual address is valid for a read of the specified
       size.

       CL_INVALID_PERMISSION if the virtual address or the size is not valid.

NOTES

       This call is only available in the kernel.  The buffer can only be accessed
       in the context of the application thread (i.e. in the path of an IOCTL
       request).  Callers cannot be holding a spinlock when calling this function.

SEE ALSO

       Memory Management, cl_check_for_write, cl_copy_to_user, cl_copy_from_user

[Functions] Component Library: Memory Management/cl_check_for_write

[top][index]

NAME

       cl_check_for_write

DESCRIPTION

       Checks a user-mode virtual address for write access.

SYNOPSIS

CL_EXPORT cl_status_t CL_API
cl_check_for_write(
        IN      void* const             vaddr,
        IN      const size_t    count );

PARAMETERS

       vaddr
               [in] Virtual address to check for write access.

       count
               [in] Number of bytes of the buffer at the specified
               address to validate.

 RETURN VALUES
       CL_SUCCESS if the virtual address is valid for a write of the specified
       size.

       CL_INVALID_PERMISSION if the virtual address or the size is not valid.

NOTES

       This call is only available in the kernel.  The buffer can only be accessed
       in the context of the application thread (i.e. in the path of an IOCTL
       request).  Callers cannot be holding a spinlock when calling this function.

SEE ALSO

       Memory Management, cl_check_for_read, cl_copy_to_user, cl_copy_from_user

[Functions] Component Library: Memory Management/cl_copy_from_user

[top][index]

NAME

       cl_copy_from_user

DESCRIPTION

       Copies data from a user-mode buffer, performing access checks.

SYNOPSIS

CL_EXPORT cl_status_t CL_API
cl_copy_from_user(
        IN      void* const                     p_dest,
        IN      const void* const       p_src,
        IN      const size_t            count );

PARAMETERS

       p_dest
               [in] Pointer to the buffer being copied to.

       p_src
               [in] User-mode virtual address from which to copy data.

       count
               [in] Number of bytes to copy from the source buffer to the
               destination buffer.

 RETURN VALUES
       CL_SUCCESS if the user-mode buffer virtual address is valid as the
       source of the copy.

       CL_INVALID_PERMISSION if the virtual address or the count is not valid.

NOTES

       This call is only available in the kernel.  The buffer can only be accessed
       in the context of the application thread (i.e. in the path of an IOCTL
       request).  Callers cannot be holding a spinlock when calling this function.

SEE ALSO

       Memory Management, cl_check_for_read, cl_check_for_write, cl_copy_to_user

[Functions] Component Library: Memory Management/cl_copy_to_user

[top][index]

NAME

       cl_copy_to_user

DESCRIPTION

       Copies data into a user-mode buffer, performing access checks.

SYNOPSIS

CL_EXPORT cl_status_t CL_API
cl_copy_to_user(
        IN      void* const                     p_dest,
        IN      const void* const       p_src,
        IN      const size_t            count );

PARAMETERS

       p_dest
               [in] User-mode virtual address to which to copy data.

       p_src
               [in] Pointer to the buffer being copied from.

       count
               [in] Number of bytes to copy from the source buffer to the
               destination buffer.

 RETURN VALUES
       CL_SUCCESS if the user-mode buffer virtual address is valid as the
       destination of the copy.

       CL_INVALID_PERMISSION if the virtual address or the count is not valid.

NOTES

       This call is only available in the kernel.  The buffer can only be accessed
       in the context of the application thread (i.e. in the path of an IOCTL
       request).  Callers cannot be holding a spinlock when calling this function.

SEE ALSO

       Memory Management, cl_check_for_read, cl_check_for_write, cl_copy_from_user

[Functions] Component Library: Memory Management/cl_free

[top][index]

NAME

       cl_free

DESCRIPTION

       The cl_free function deallocates a block of memory.

SYNOPSIS

void
cl_free(
        IN      void* const     p_memory );

PARAMETERS

       p_memory
               [in] Pointer to a memory block.

RETURN VALUE

       This function does not return a value.

NOTES

       The p_memory parameter is the pointer returned by a previous call to
       cl_malloc, or cl_zalloc.

       cl_free has no effect if p_memory is NULL.

SEE ALSO

       Memory Management, cl_alloc, cl_zalloc

[Functions] Component Library: Memory Management/cl_get_pagesize

[top][index]

NAME

       cl_get_pagesize

DESCRIPTION

       Returns the number of bytes in a OS defined page.

SYNOPSIS

CL_EXPORT uint32_t CL_API
cl_get_pagesize( void );

PARAMETERS

       NONE

 RETURN VALUES
       Returns the number of bytes in a page as defined by the Operating
       System.

SEE ALSO

       Memory Management

[Functions] Component Library: Memory Management/cl_get_physaddr

[top][index]

NAME

       cl_get_physaddr

DESCRIPTION

       Returns the Physical address for a kernel virtual address.

SYNOPSIS

CL_EXPORT uint64_t CL_API
cl_get_physaddr(
        IN      void *vaddr );

PARAMETERS

       p_addr
               [in] Pointer to virtual to which the physical address is required.

 RETURN VALUES
       Returns the physical address for a virtual address.

NOTES

       This call is only available in kernel mode.

SEE ALSO

       Memory Management

[Functions] Component Library: Memory Management/cl_malloc

[top][index]

NAME

       cl_malloc

DESCRIPTION

       The cl_malloc function allocates a block of memory.

SYNOPSIS

void*
cl_malloc(
        IN      const size_t    size );

PARAMETERS

       size
               [in] Size of the requested allocation.

 RETURN VALUES
       Pointer to allocated memory if successful.

       NULL otherwise.

NOTES

       Allocated memory follows alignment rules specific to the different
       environments.

SEE ALSO

       Memory Management, cl_free, cl_zalloc, cl_palloc, cl_pzalloc,
       cl_memset, cl_memclr, cl_memcpy, cl_memcmp

[Functions] Component Library: Memory Management/cl_mem_display

[top][index]

NAME

       cl_mem_display

DESCRIPTION

       The cl_mem_display function displays all tracked memory allocations to
       the applicable debugger.

SYNOPSIS

CL_EXPORT void CL_API
cl_mem_display( void );

RETURN VALUE

       This function does not return a value.

NOTES

       Each tracked memory allocation is displayed along with the file name and
       line number that allocated it.

       Output is sent to the platform's debugging target, which may be the
       system log file.

SEE ALSO

       Memory Management

[Functions] Component Library: Memory Management/cl_memclr

[top][index]

NAME

       cl_memclr

DESCRIPTION

       The cl_memclr function sets every byte in a memory range to zero.

SYNOPSIS

CL_INLINE void CL_API
cl_memclr(
        IN      void* const             p_memory,
        IN      const size_t    count )
{
        cl_memset( p_memory, 0, count );
}

PARAMETERS

       p_memory
               [in] Pointer to a memory block.

       count
               [in] Number of bytes to set.

RETURN VALUE

       This function does not return a value.

SEE ALSO

       Memory Management, cl_memset, cl_memcpy, cl_memcmp

[Functions] Component Library: Memory Management/cl_memcmp

[top][index]

NAME

       cl_memcmp

DESCRIPTION

       The cl_memcmp function compares two memory buffers.

SYNOPSIS

CL_EXPORT int32_t CL_API
cl_memcmp(
        IN      const void* const       p_mem,
        IN      const void* const       p_ref,
        IN      const size_t            count );

PARAMETERS

       p_mem
               [in] Pointer to a memory block being compared.

       p_ref
               [in] Pointer to the reference memory block to compare against.

       count
               [in] Number of bytes to compare.

 RETURN VALUES
       Returns less than zero if p_mem is less than p_ref.

       Returns greater than zero if p_mem is greater than p_ref.

       Returns zero if the two memory regions are the identical.

SEE ALSO

       Memory Management, cl_memset, cl_memclr, cl_memcpy

[Functions] Component Library: Memory Management/cl_memcpy

[top][index]

NAME

       cl_memcpy

DESCRIPTION

       The cl_memcpy function copies a given number of bytes from
       one buffer to another.

SYNOPSIS

CL_EXPORT void* CL_API
cl_memcpy(
        IN      void* const                     p_dest,
        IN      const void* const       p_src,
        IN      const size_t            count );

PARAMETERS

       p_dest
               [in] Pointer to the buffer being copied to.

       p_src
               [in] Pointer to the buffer being copied from.

       count
               [in] Number of bytes to copy from the source buffer to the
               destination buffer.

RETURN VALUE

       Returns a pointer to the destination buffer.

SEE ALSO

       Memory Management, cl_memset, cl_memclr, cl_memcmp

[Functions] Component Library: Memory Management/cl_memset

[top][index]

NAME

       cl_memset

DESCRIPTION

       The cl_memset function sets every byte in a memory range to a given value.

SYNOPSIS

CL_EXPORT void CL_API
cl_memset(
        IN      void* const             p_memory,
        IN      const uint8_t   fill,
        IN      const size_t    count );

PARAMETERS

       p_memory
               [in] Pointer to a memory block.

       fill
               [in] Byte value with which to fill the memory.

       count
               [in] Number of bytes to set.

RETURN VALUE

       This function does not return a value.

SEE ALSO

       Memory Management, cl_memclr, cl_memcpy, cl_memcmp

[Functions] Component Library: Memory Management/cl_palloc

[top][index]

NAME

       cl_palloc

DESCRIPTION

       The cl_palloc function allocates a block of memory from paged pool if the
       operating system supports it.  If the operating system does not distinguish
       between pool types, cl_palloc is identical to cl_malloc.

SYNOPSIS

void*
cl_palloc(
        IN      const size_t    size );

PARAMETERS

       size
               [in] Size of the requested allocation.

 RETURN VALUES
       Pointer to allocated memory if successful.

       NULL otherwise.

NOTES

       Allocated memory follows alignment rules specific to the different
       environments.

SEE ALSO

       Memory Management, cl_free, cl_malloc, cl_zalloc, cl_pzalloc,
       cl_memset, cl_memclr, cl_memcpy, cl_memcmp

[Functions] Component Library: Memory Management/cl_pzalloc

[top][index]

NAME

       cl_pzalloc

DESCRIPTION

       The cl_pzalloc function allocates a block of memory from paged pool if the
       operating system supports it and initializes it to zero.  If the operating
       system does not distinguish between pool types, cl_pzalloc is identical
       to cl_zalloc.

SYNOPSIS

void*
cl_pzalloc(
        IN      const size_t    size );

PARAMETERS

       size
               [in] Size of the requested allocation.

 RETURN VALUES
       Pointer to allocated memory if successful.

       NULL otherwise.

NOTES

       Allocated memory follows alignment rules specific to the different
       environments.

SEE ALSO

       Memory Management, cl_free, cl_malloc, cl_zalloc, cl_palloc,
       cl_memset, cl_memclr, cl_memcpy, cl_memcmp

[Functions] Component Library: Memory Management/cl_zalloc

[top][index]

NAME

       cl_zalloc

DESCRIPTION

       The cl_zalloc function allocates a block of memory initialized to zero.

SYNOPSIS

void*
cl_zalloc(
        IN      const size_t    size );

PARAMETERS

       size
               [in] Size of the requested allocation.

 RETURN VALUES
       Pointer to allocated memory if successful.

       NULL otherwise.

NOTES

       Allocated memory follows alignment rules specific to the different
       environments.

SEE ALSO

       Memory Management, cl_free, cl_malloc, cl_palloc, cl_pzalloc,
       cl_memset, cl_memclr, cl_memcpy, cl_memcmp