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.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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