autohbw(7)

1AUTOHBW(7)                          AUTOHBW                         AUTOHBW(7)
2
3
4

NAME

6       libautohbw.so - An interposer library for redirecting heap allocations
7

SYNOPSIS

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

DESCRIPTION

12       AutoHBW  library (libautohbw.so) is an interposer library for redirect‐
13       ing heap allocations (malloc, calloc, realloc, valloc,  posix_memalign,
14       memlign)  to high-bandwidth (HBW) memory. Consequently, AutoHBW library
15       can be used to automatically allocate high-bandwidth memory without any
16       modification to source code of an application.
17
18       For  instance,  the following command-line runs existing binary /bin/ls
19       with  AutoHBW  library,  automatically  redirecting  heap   allocations
20       (larger than a given threshold) to high-bandwidth memory.
21
22              LD_PRELOAD=libautohbw.so /bin/ls
23
24

ENVIRONMENT

26       The behavior of AutoHBW library is controlled by the following environ‐
27       ment variables.
28
29
30       AUTO_HBW_SIZE=x:[y]
31       Indicates that any allocation larger than x and smaller than  y  should
32       be allocated in HBW memory.  x and y can be followed by a K, M, or G to
33       indicate the size in Kilo/Memga/Giga bytes (e.g., 4K, 3M, 2G).
34
35       Examples:
36
37       AUTO_HBW_SIZE=4K
38              # allocations larger than 4K allocated in HBW
39
40       AUTO_HBW_SIZE=1M:5M
41              # allocations between 1M and 5M allocated in HBW
42
43
44       AUTO_HBW_LOG=level
45       Sets the value of logging (printing) level.  If level is:
46
47       -1     no messages are printed
48
49       0      no allocations  messages  are  printed  but  INFO  messages  are
50              printed
51
52       1      a log message is printed for each allocation (Default)
53
54       2      a  log  message is printed for each allocation with a backtrace.
55              Redirect this output and use  autohbw_get_src_lines.pl  to  find
56              source  lines for each allocation. Your application must be com‐
57              piled with -g to see source lines.
58
59       Notes:
60
61              1. Logging adds extra overhead. Therefore, for performance crit‐
62              ical runs, logging level should be 0
63
64              2.  The  amount of free memory printed with log messages is only
65              approximate -- e.g. pages that are not touched yet are excluded
66
67       Examples:
68
69       AUTO_HBW_LOG=1
70
71
72       AUTO_HBW_MEM_TYPE=memory_type
73       Sets the type of memory type that should be automatically allocated. By
74       default, this type is MEMKIND_HBW_PREFERRED, if MCDRAM is found in your
75       system; otherwise, the default is MEMKIND_DEFAULT. The names of  memory
76       types are defined in memkind(3) man page.  memory_type has to be one of
77       MEMKIND_DEFAULT,  MEMKIND_HUGETLB,   MEMKIND_INTERLEAVE,   MEMKIND_HBW,
78       MEMKIND_HBW_PREFERRED,       MEMKIND_HBW_HUGETLB,      MEMKIND_HBW_PRE‐
79       FERRED_HUGETLB,   MEMKIND_HBW_GBTLB   (DEPRECATED),    MEMKIND_HBW_PRE‐
80       FERRED_GBTLB  (DEPRECATED), MEMKIND_GBTLB (DEPRECATED), MEMKIND_HBW_IN‐
81       TERLEAVE
82
83       If you are requesting any huge TLB pages, please make sure that the re‐
84       quested type is currently enabled in your OS.
85
86       Examples:
87
88       AUTO_HBW_MEM_TYPE=MEMKIND_HBW_PREFERRED
89              # (default, if MCDRAM present)
90
91       AUTO_HBW_MEM_TYPE=MEMKIND_DEFAULT
92              # (default, if MCDRAM absent)
93
94       AUTO_HBW_MEM_TYPE=MEMKIND_HBW_HUGETLB
95
96       AUTO_HBW_MEM_TYPE=MEMKIND_HUGETLB
97
98
99       AUTO_HBW_DEBUG=0|1|2
100       Set  the debug message printing level. Default is 0. This is mainly for
101       development.
102
103

NOTES

105       It is possible to temporarily disable/enable automatic HBW  allocations
106       by calling disableAutoHBW() and enableAutoHBW() in source code. To call
107       these routines, please include autohbw_api.h header file and link  with
108       -lautohbw.
109
110
111       If  high-bandwidth memory is not physically present in your system, the
112       environment variable MEMKIND_HBW_NODES must  be  set  to  indicate  the
113       high-bandwidth node as indicated in memkind(3).
114
115
116

EXAMPLES

118       The  following  will  run  /bin/ls with AutoHBW library. Make sure that
119       paths to both libautohbw.so and libmemkind.so are  included  in  LD_LI‐
120       BRARY_PATH.
121
122              LD_PRELOAD=libautohbw.so /bin/ls -l
123
124       To  run  with  MPI,  a  shell  script must be created, with the correct
125       LD_PRELOAD  command  for  each   rank.   For   example,   if   we   put
126       LD_PRELOAD=libautohbw.so   /bin/ls   in  a  shell  script  named  auto‐
127       hbw_test.sh, it can be executed with 2 MPI ranks as:
128
129              mpirun -n 2 ./autohbw_test.sh
130
131

COPYRIGHT

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