memkind_gbtlb (3) - Linux Manuals

memkind_gbtlb: gigabyte TLB memkind operations.

NAME

memkind_gbtlb.h - gigabyte TLB memkind operations.
Note: This is EXEPRIMENTAL API. The functionality and the header file itself can be changed (including non-backward compatible changes), or remove.

SYNOPSIS

#include <memkind/internal/memkind_gbtlb.h>

Link with -lmemkind

void *memkind_gbtlb_malloc(struct memkind *kind, size_t size);
void *memkind_gbtlb_calloc(struct memkind *kind, size_t num, size_t size);
int memkind_gbtlb_posix_memalign(struct memkind *kind, void **memptr, size_t alignment, size_t size);
void *memkind_gbtlb_realloc(struct memkind *kind, void *ptr, size_t size);
void memkind_gbtlb_free(struct memkind *kind, void *ptr);
int memkind_gbtlb_get_mmap_flags(struct memkind *kind, int *flags);
int memkind_gbtlb_check_addr(struct memkind *kind, void *addr);

DESCRIPTION

Gigabyte TLB implementations for memkind operations. These are implemented without using the jemalloc library. The implementation is a wrapper around mmap(2) with a hash table for storing the address and extent of the mapped memory. The hash table is queried when freeing memory in order to determine the extent that should be passed to munmap(2) The reason for using such a simplified implementation instead of using a heap is that a heap manager is intended to mitigate the overhead of the mmap(2) system call by calling it less frequently than the allocation requests that is services. Since there is a large amount of memory being allocated with each call in the case where there are gigabyte pages backing the allocation, the frequency of requests is assumed to be low. For this reason the traditional requirements of a heap manager to be faster than directly mapping memory from the operating system is relaxed.

memkind_gbtlb_malloc() calls mmap(2) with MAP_HUGE_1GB mmap flag for allocating gigabyte pages for size bytes and kind can take MEMKIND_GBTLB, MEMKIND_HBW_GBTLB, MEMKIND_HBW_GBTLB_PREFERRED and stores the returned address in the internal hash table which can be queried to support the memkind_gbtlb_free() operation. If kind does not support GBTLB undefined behaviour occurs.

memkind_gbtlb_calloc() is exactly the same implementation and supports the same kind as memkind_gbtlb_malloc() since the mmap(2) system call is guaranteed to return memory of size bytes which has been zeroed.

memkind_gbtlb_posix_memalign() is a similar implementation to memkind_gbtlb_malloc() except that the returned address will be aligned as requested, and the error code returned will reflect the POSIX standard defined in errno.h. memkind_gbtlb_posix_memalign the return pointer for the allocated memory

memkind_gbtlb_realloc() can be used to extend or shrink an allocation previously created by one of the other interfaces defined here. Implementation reuses memkind_gbtlb_malloc() for allocating the new size of memory if needed. There is an optimization in place so that if a partial page was previously allocated then it can be extended to the end of the page transparently. (Details in NOTE)

memkind_gbtlb_free() queries the hash table to find the extent of the memory associated with the address passed by the user. It then calls munmap(2) on that extent.

memkind_gbtlb_get_mmap_flags() Sets the flags appropriately for requesting anonymous gigabyte pages.

memkind_gbtlb_check_addr() queries the hash table to determine if the address reflects an extent previously allocated with one of the interfaces defined here, and returned 03 exact kind associated with the address.

INTERNAL STATIC FUNCTIONS

memkind_store() implements a hash table with a hash value calculated using the crc32 SIMD instruction which returns crc+CRC-32C(v) where v is the virtual address pointer. This hash table is used to store the virtual address for retrieval and freeing. The table, stores the requested size, allocated size, the virtual address pointer and the mmap'ed address pointer information.

memkind_gbtlb_ceil_size() differentiates between STRICT and REGULAR gbtlb implementations by getting the ceil of the size if the requested size is not a modulo of a gigabyte.

memkind_gbtlb_check_addr() function looks in the gbtlb hash table to see if the virtual address was allocated with GB pages. This feature is used in determining the kind for realloc'ing in the hbw_realloc implementation.

NOTES

memkind_gbtlb_realloc() is special, as it allows to use the same page that was fetched. Since this implementation of gigabyte pages is not backed by an actual heap manager like other kinds (which use jemalloc), each allocation request would fetch a gigabyte page. So when a realloc is called on a virtual address pointer backed by a GB page which has not been completely used, and if the current request including previous request does not exceed a GB, no more pages are allocated. To summarize, realloc implementation of MEMKIND_GBTLB guarantees that gigabyte pages get allocated when its actually needed.

memkind_gbtlb_free() is a little different from the free of the other kinds. Since the other kinds are backed by jemalloc, a free will recycle the pages in recycle pools maintained by jemalloc, in the case of the gbtlb, the pages are actually returned to the operating system.

REQUIREMENTS

To allocated gigabyte pages from the operating system. This can be done by specifying hugepagesz=1G nr_hugepages=N on the kernel commandline. From 3.16 and later kernels, users can allocate gigabyte pages like its done for 2MB pages. i.e echo no_pages > /proc/sys/vm/nr_hugepages

COPYRIGHT

Copyright (C) 2014 - 2016 Intel Corporation. All rights reserved.