.\" SPDX-License-Identifier: BSD-2-Clause
.\" Copyright (C) 2022 Intel Corporation.
.\"
.TH MEMTIER 1 2022-02-21 "Intel Corporation" MEMTIER \" -*- nroff -*-
.SH NAME

memtier \- redirect malloc calls to memkind memory tiering

.SH SYNOPSIS

.B memtier
.R [
.B -r
.I ratio
.R ] [
.B -t
.I thresholds
.R ]
.I program args...

.SH DESCRIPTION

.B memtier
runs the given \fIprogram\fR, redirecting memory allocations to different
memory tiers based on a given policy.  This allows unmodified programs to
run following a non-greedy allocation scheme that avoids a performance cliff
when DRAM is exhausted.

.SH OPTIONS

.TP
.BR "-r " ratio
Specifies the ratio as a pair of integers separated by a colon, where the
first number gives the relative share of near DRAM to be used while the
second number gives "far" memory, be it CXL memory or PMEM.  Eg.
\fI"1:4"\fR means that 20% of allocations will use DRAM, 80% PMEM.

If the ratio is not given, it defaults to the relative share of physically
installed memory.

This version of memtier recognizes only two tiers (DRAM and KMEM_DAX).

.TP
.BR "-t " thresholds
Turns on DYNAMIC_THRESHOLD mode where small allocations are served from
DRAM and large ones from far memory.  The syntax is described in depth
in \fBman libmemtier\fR, eg.
.I -t "INIT_VAL=1024,MIN_VAL=512,MAX_VAL=65536"
starts with a threshold of 1024, then varies it between 512..65536
attempting to match the requested ratio.

.TP
.BR "-v"
Displays settings that are passed to \fBlibmemtier\fR.

.TP
.BR "-h"
Shows a help message then exits.

.SH CAVEATS

This tool doesn't expose all features of \fBlibmemtier\fR.  Only DRAM and
KMEM_DAX memory is supported, to use FS_DAX you need to configure the
library directly, please refer to its man page.

Or alternatively, you can switch that memory to KMEM_DAX mode.  For that
purpose, please refer to "man ndctl-reconfigure-namespace" and "man
daxctl-reconfigure-device".

.SH "SEE ALSO"
.BR libmemtier(7) ,
.BR memkind(3) ,
.BR malloc(3)