AUTOHBW(7)

✨ AUTOHBW — the libautohbw.so glow-up ✨

ok so bestie, welcome to AUTOHBW(7), aka the manual page for libautohbw.so — an interposer library for redirecting heap allocations. it's giving malloc-but-make-it-fast 💅

---

🎀 SYNOPSIS

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

---

🌸 DESCRIPTION

k so here's the tea. AutoHBW library (libautohbw.so) is an interposer library for redirecting heap allocations — and by "heap allocations" I mean malloc, calloc, realloc, valloc, posix_memalign, and memlign — straight into high-bandwidth (HBW) memory. and the way that means you can just… automatically allocate high-bandwidth memory without touching a single line of your application's source code?? iconic behavior, no notes 🫶

like, for instance, this command-line right here runs the existing binary /bin/ls with the AutoHBW library, and it automatically redirects heap allocations (the ones bigger than a given threshold) to high-bandwidth memory:

LD_PRELOAD=libautohbw.so /bin/ls

literally zero source changes. the app doesn't even know. main character energy fr fr ✨

---

🦋 ENVIRONMENT

the behavior of the AutoHBW library is controlled by these environment variables, and you're gonna want to know all of them:

AUTO_HBW_SIZE=x:[y]

says 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 the 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. do not skip this step bestie, it will not be cute.

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 the autohbw_api.h header file and link with -lautohbw. (yes, actual code this time. she contains multitudes.)

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). don't forget it or it's gonna be a whole thing 😭

---

🔥 EXAMPLES

the following will run /bin/ls with the 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

slay. go forth and interpose 🧚

---

👑 COPYRIGHT

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

---

🌈 SEE ALSO

• memkind(3)
• malloc(3)
• numactl(8)

---

and that's the whole page bestie, tysm for reading 💖 this one came from Intel Corporation, dated 2016-07-28, and it lives in section AUTOHBW(7). periodt. 💅