.\" SPDX-License-Identifier: BSD-2-Clause

.\" Copyright (C) 2014 - 2020 Intel Corporation.

.\"

.TH "AUTOHBW" 7 "2016-07-28" "Intel Corporation" "AUTOHBW" \" -*- nroff -*-

.SH "NAME"

libautohbw.so \- An interposer library for redirecting heap allocations

.SH "SYNOPSIS"

.BR LD_PRELOAD=libautohbw.so

command {arguments ...}

.SH "DESCRIPTION"

.B AutoHBW

library

.BR (libautohbw.so)

is an interposer library for redirecting heap allocations

.B (malloc, calloc, realloc, valloc, posix_memalign, memlign)

to high-bandwidth

.B (HBW)

memory. Consequently, AutoHBW library can be used to

automatically allocate high-bandwidth memory without any modification to

source code of an application.

.br

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.

.IP

.B LD_PRELOAD=libautohbw.so

/bin/ls

.SH "ENVIRONMENT"

The behavior of AutoHBW library is controlled by the following environment

variables.

.PP

.B AUTO_HBW_SIZE=x:[y]

.br

Indicates that any allocation larger than

.I x

and smaller than

.I y

should be

allocated in HBW memory.

.I x

and

.I y

can be followed by a K, M, or G to indicate

the size in Kilo/Memga/Giga bytes (e.g., 4K, 3M, 2G).

.br

Examples:

.IP AUTO_HBW_SIZE=4K

# allocations larger than 4K allocated in HBW

.IP AUTO_HBW_SIZE=1M:5M

# allocations between 1M and 5M allocated in HBW

.PP

.B AUTO_HBW_LOG=level

.br

Sets the value of logging (printing)

.I level.

If

.I level

is:

.br

.IP -1

no messages are printed

.br

.IP 0

no allocations messages are printed but INFO messages are printed

.br

.IP 1

a log message is printed for each allocation (Default)

.br

.IP 2

a log message is printed for each allocation with a backtrace.

Redirect this output and use

.B autohbw_get_src_lines.pl

to find source lines for each allocation. Your application must

be compiled with

.B -g

to see source lines.

.PP

Notes:

.IP

1. Logging adds extra overhead. Therefore, for performance

critical runs, logging level should be 0

.IP

2. The amount of free memory printed with log messages is only

approximate -- e.g. pages that are not touched yet are excluded

.PP

Examples:

.IP AUTO_HBW_LOG=1

.PP

.B AUTO_HBW_MEM_TYPE=memory_type

.br

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

.B memkind(3)

man page.

.B memory_type

has to be one of

.B MEMKIND_DEFAULT, MEMKIND_HUGETLB, MEMKIND_INTERLEAVE, MEMKIND_HBW,

.B MEMKIND_HBW_PREFERRED, MEMKIND_HBW_HUGETLB, MEMKIND_HBW_PREFERRED_HUGETLB,

.B MEMKIND_HBW_GBTLB (DEPRECATED), MEMKIND_HBW_PREFERRED_GBTLB (DEPRECATED), MEMKIND_GBTLB (DEPRECATED),

.B 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:

.IP AUTO_HBW_MEM_TYPE=MEMKIND_HBW_PREFERRED

# (default, if MCDRAM present)

.IP AUTO_HBW_MEM_TYPE=MEMKIND_DEFAULT

# (default, if MCDRAM absent)

.IP AUTO_HBW_MEM_TYPE=MEMKIND_HBW_HUGETLB

.IP AUTO_HBW_MEM_TYPE=MEMKIND_HUGETLB

.PP

.B AUTO_HBW_DEBUG=0|1|2

.br

Set the debug message printing level. Default is 0. This is mainly for

development.

.SH "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

.B autohbw_api.h

header file and link with -lautohbw.

.br

If high-bandwidth memory is not physically present in your system,

the environment variable

.B MEMKIND_HBW_NODES

must be set to indicate the high-bandwidth node as indicated in

.B memkind(3).

.SH "EXAMPLES"

.br

The following will run /bin/ls with AutoHBW library. Make sure that paths to

both libautohbw.so and libmemkind.so are included in

.B LD_LIBRARY_PATH.

.IP

.B LD_PRELOAD=libautohbw.so

/bin/ls -l

.PP

To run with MPI, a shell script must be created, with the correct LD_PRELOAD

command for each rank. For example, if we put

.B LD_PRELOAD=libautohbw.so /bin/ls

in a shell script named autohbw_test.sh, it can be executed with 2 MPI ranks as:

.br

.IP

.B mpirun -n 2 ./autohbw_test.sh

.SH "COPYRIGHT"

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

.SH "SEE ALSO"

.BR memkind(3)

.BR malloc (3),

.BR numactl (8),