========================================================================
README for Membw tool

Mar 2024

========================================================================

Contents
========

- Overview
- Requirements and Installation
- Usage
- Limitations
- Legal Disclaimer


Overview
========

The membw software tool provides a way to stress local and remote memory
bandwidth using a variety of memory operations. The tool allows the user
to choose an operation to generate a specified amount of memory bandwidth
on a selected core.

Requirements and Installation
=============================

For installation of the Intel(R) Membw tool follow below instructions:

To compile:
        "make" for building tool
        "make clean" for clearing all object files

Usage
=====

Usage: For Membw:
    "./membw --help"   This option will display extensive help page.
                       Please refer to "--help" option for usage details

    "./membw -c <cpu> -b <BW [MB/s]> <operation type>"

        <cpu> Select CPU ID to generate bandwidth

        <BW [MB/s]> Select amount of bandwidth to generate

        <operation type> Select operation type from the following list
          --prefetch-t0      prefetcht0
          --prefetch-t1      prefetcht1
          --prefetch-t2      prefetcht2
          --prefetch-nta     prefetchtnta
          --prefetch-w       prefetchw
          --read             x86 loads
          --read-sse         SSE loads
          --nt-read-sse      SSE NT loads
          --read-mod-write   x86 load XOR write
          --write            x86 stores
          --write-avx512     AVX512 stores
          --write-clwb       x86 stores + clwb
          --write-flush      x86 stores & clflush (naturally generates loads & stores)
          --write-sse        SSE stores
          --write-sse-flush  SSE stores & clflush (naturally generates loads & stores)
          --nt-write         x86 NT stores
          --nt-write-avx512  AVX512 NT stores
          --nt-write-clwb    x86 NT stores + clwb
          --nt-write-sse     SSE NT stores

Limitations
===========

The tool allocates a chunk of memory as much as twice of LLC physical cache size.
It uses standard means of the C library for that allocation. Therefore it is
affected by all OS placement policy limitations such as NUMA-awareness, etc...
For example, when SNC is enabled NUMA-aware OS allocates only addresses local to
the SNC-domain and only SNC-domain local cache slices are populated. In the case
of SNC-2 it populates 50% of cache slices. For SNC-3 the population will be 33%.
For SNC-4 only 25% of the cache will be populated.
Possibly there are other limitations exist/will exist on OS or/and hardware level
that will prevent the tool from populating 100% of cache/memory bandwidth.

Legal Disclaimer
================

THIS SOFTWARE IS PROVIDED BY INTEL"AS IS". NO LICENSE, EXPRESS OR
IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS
ARE GRANTED THROUGH USE. EXCEPT AS PROVIDED IN INTEL'S TERMS AND
CONDITIONS OF SALE, INTEL ASSUMES NO LIABILITY WHATSOEVER AND INTEL
DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR
USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO
FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT
OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.
