NAME

       libautohbw.so - An interposer library for redirecting heap allocations

SYNOPSIS

       LD_PRELOAD=libautohbw.so command {arguments ...}

DESCRIPTION

       AutoHBW  library  (libautohbw.so)  is  an  interposer  library  for redirecting heap allocations (malloc,
       calloc, realloc, valloc, posix_memalign, memlign) to high-bandwidth (HBW) memory.  Consequently,  AutoHBW
       library  can  be  used to automatically allocate high-bandwidth memory without any modification to source
       code of an application.

       For instance, the following command-line runs existing binary /bin/ls with AutoHBW library, automatically
       redirecting heap allocations (larger than a given threshold) to high-bandwidth memory.

              LD_PRELOAD=libautohbw.so /bin/ls

ENVIRONMENT

       The behavior of AutoHBW library is controlled by the following environment variables.

       AUTO_HBW_SIZE=x:[y]
       Indicates  that any allocation larger than x and smaller than y should be allocated in HBW memory.  x and
       y can be followed by a K, M, or G to indicate the size in Kilo/Memga/Giga bytes (e.g., 4K, 3M, 2G).

       Examples:

       AUTO_HBW_SIZE=4K
              # allocations larger than 4K allocated in HBW

       AUTO_HBW_SIZE=1M:5M
              # allocations between 1M and 5M allocated in HBW

       AUTO_HBW_LOG=level
       Sets the value of logging (printing) level.  If level is:

       -1     no messages are printed

       0      no allocations messages are printed but INFO messages are printed

       1      a log message is printed for each allocation (Default)

       2      a log message is printed for each allocation with a  backtrace.   Redirect  this  output  and  use
              autohbw_get_src_lines.pl  to  find  source  lines  for  each  allocation. Your application must be
              compiled with -g to see source lines.

       Notes:

              1. Logging adds extra overhead. Therefore, for performance critical runs, logging level should  be
              0

              2.  The amount of free memory printed with log messages is only approximate -- e.g. pages that are
              not touched yet are excluded

       Examples:

       AUTO_HBW_LOG=1

       AUTO_HBW_MEM_TYPE=memory_type
       Sets the type of  memory  type  that  should  be  automatically  allocated.  By  default,  this  type  is
       MEMKIND_HBW_PREFERRED,  if MCDRAM is found in your system; otherwise, the default is MEMKIND_DEFAULT. The
       names of memory types are defined in memkind(3) man page.  memory_type has to be one of  MEMKIND_DEFAULT,
       MEMKIND_HUGETLB,    MEMKIND_INTERLEAVE,    MEMKIND_HBW,    MEMKIND_HBW_PREFERRED,    MEMKIND_HBW_HUGETLB,
       MEMKIND_HBW_PREFERRED_HUGETLB, MEMKIND_HBW_GBTLB (DEPRECATED), MEMKIND_HBW_PREFERRED_GBTLB  (DEPRECATED),
       MEMKIND_GBTLB (DEPRECATED), MEMKIND_HBW_INTERLEAVE

       If  you  are requesting any huge TLB pages, please make sure that the requested type is currently enabled
       in your OS.

       Examples:

       AUTO_HBW_MEM_TYPE=MEMKIND_HBW_PREFERRED
              # (default, if MCDRAM present)

       AUTO_HBW_MEM_TYPE=MEMKIND_DEFAULT
              # (default, if MCDRAM absent)

       AUTO_HBW_MEM_TYPE=MEMKIND_HBW_HUGETLB

       AUTO_HBW_MEM_TYPE=MEMKIND_HUGETLB

       AUTO_HBW_DEBUG=0|1|2
       Set the debug message printing level. Default is 0. This is mainly for development.

NOTES

       It is possible to temporarily disable/enable automatic HBW allocations by  calling  disableAutoHBW()  and
       enableAutoHBW() in source code. To call these routines, please include autohbw_api.h header file and link
       with -lautohbw.

       If  high-bandwidth  memory  is  not  physically  present  in  your  system,  the   environment   variable
       MEMKIND_HBW_NODES must be set to indicate the high-bandwidth node as indicated in memkind(3).

EXAMPLES

       The  following  will  run  /bin/ls  with  AutoHBW library. Make sure that paths to both libautohbw.so and
       libmemkind.so are included in LD_LIBRARY_PATH.

              LD_PRELOAD=libautohbw.so /bin/ls -l

       To run with MPI, a shell script must be created, with the correct LD_PRELOAD command for each  rank.  For
       example,  if  we  put LD_PRELOAD=libautohbw.so /bin/ls in a shell script named autohbw_test.sh, it can be
       executed with 2 MPI ranks as:

              mpirun -n 2 ./autohbw_test.sh

COPYRIGHT

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

SEE ALSO

       memkind(3) malloc(3), numactl(8),