Provided by: libmemkind-dev_1.1.0-0ubuntu1_amd64 
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.
SEE ALSO
memkind(3), memkind_arena(3), memkind_default(3), memkind_hbw(3), memkind_hugetlb(3), memkind_pmem(3), jemalloc(3), mbind(2), mmap(2)