PMFuzz

PMFuzz is a testcase generation tool to generate high-value tests cases for PM testing tools (XFDetector, PMDebugger, PMTest and Pmemcheck)

If you find PMFuzz useful in your research, please cite:

Sihang Liu, Suyash Mahar, Baishakhi Ray, and Samira Khan
PMFuzz: Test Case Generation for Persistent Memory Programs
The International Conference on Architectural Support for Programming Languages and Operating Systems (ASPLOS), 2021

BibTex

Dependencies

PMFuzz was tested using the following environment configuration, other versions may work:

  1. Ubuntu 18.04
  2. NDCTL v64 or higher
  3. libunwind (libunwind-dev)
  4. libini-config (libini-config-dev)
  5. Python 3.8
  6. GNUMake >= 3.82
  7. Kernel version 5.4
  8. Anaconda or virtualenv (recommended)

For compiling documentation:

  1. doxygen
  2. pdflatex
  3. doxypypy

Compiling PMFuzz

Build PMFuzz and AFL

make -j $(nproc --all)

Install PMFuzz

sudo make install

Now, pmfuzz-fuzz should be available as an executable:

pmfuzz-fuzz --help

The following man pages are also installed:

man 1 pmfuzz-fuzz
man 7 libpmfuzz
man 7 libfakepmfuzz

To uninstall PMFuzz, run the following command:

sudo make uninstall

Compiling PMFuzz Docker image

PMFuzz also comes with a docker file to automatically configure and install pmfuzz. To build the image, run the following command from the root of the repository:

docker build -t pmfuzz-v0.9 .

The raw dockerfile is also available here: /Dockerfile.

Using PMFuzz

After installing PMFuzz, use annotations by including the PMFuzz header file:

#include "pmfuzz/pmfuzz.h" int main() { printf("PMFuzz version: %s\n", pmfuzz_version_str); }

The program would then have to be linked with either libpmfuzz or libfakepmfuzz. e.g.,

example: example.o $(CXX) -o $@ $< -lfakepmfuzz # or -lpmfuzz

To compile a program linked with libpmfuzz, you'd need to use PMFuzz's AFL++ version of gcc/clang. Check build/bin after building PMFuzz.

For debugging, libfakepmfuzz exports the same interface but no actual tracking mechanism, allowing it to compile with any C/C++ compiler.

An example program is available in src/example. The original ASPLOS 2021 artifact is available at https://github.com/Systems-ShiftLab/pmfuzz_asplos21_ae.

libpmfuzz API is available at docs/libpmfuzz.7.md

Compiling Documentation

Run make docs from the root, and all the documentation will be linked in the docs/ directory.

Some man pages are available as markdown formatted files:

  1. docs/libpmfuzz.7.md
  2. docs/pmfuzz-fuzz.1.md

Running custom configuration

PMFuzz uses a YML based configuration to set different parameters for fuzzing, to write a custom configuration, please follow one of the existing examples in src/pmfuzz/configs/examples/ directory.

More information on PMFuzz's syntax is here.

Modifying PMFuzz

PMFuzz was written in a modular way allowing part of PMFuzz's components to be swapped with something that has the same interface. If you have a question please open a new issue or a discussion.

Other useful information

Env variables

NOTE: If a variable doesn't have a possible value next to it, that variable would be enabled by setting it to any non-empty value (including 0).

  1. USE_FAKE_MMAP=(0,1): Enables fake mmap which mounts an image in the volaile memory.
  2. PMEM_MMAP_HINT=<addr>: Address of the mount point of the pool.
  3. ENABLE_CNST_IMG=(0,1): Disables default PMDK's behaviour that generates non-identical images for same input.
  4. FI_MODE=(<empty or unset>|IMG_GEN|IMG_REP): See libpmfuzz.c
  5. FAILURE_LIST=<path-to-output-file>: See libpmfuzz.c
  6. PMFUZZ_DEBUG=(0,1): Enables debug output from libpmfuzz
  7. ENABLE_PM_PATH: Enables deep paths in PMFuzz
  8. GEN_ALL_CS: Partially disables the probabilistic generation of crash sites and more of them are generated from libpmfuzz.c
  9. IMG_CREAT_FINJ: Disables the probabilistic generation of crash sites and all of them are generated from libpmfuzz.c
  10. PMFUZZ_SKIP_TC_CHECK: Disable testcase size check in AFL++
  11. PRIMITIVE_BASELINE_MODE: Makes workload delete image on start if the pool exists

Adding git hook for development

Following command adds a pre-commit hook to check if the tests pass:

git config --local core.hooksPath .githooks/

Reasons for Common errors

1. FileNotFoundError for instance's pid file

Raised when AFL cannot bind to a free core or no core is free.

2. Random tar command failed

Check if no free disk space is left on the device

3. shmget (2): No space left on device

Run:

ipcrm -a

Warning: This removes all user owned shared memory segments, don't run with superuser privilege or on a machine with other critical applications running.

Licensing

PMFuzz is licensed under BSD-3-clause except noted otherwise.

PMFuzz uses of the following open-source software:

  1. Preeny (license)
    Preeny was modified to fix a bug in desock. All changes are contained in vendor/pathes/preeny_path
  2. AFL++ (license)
    AFL++ was modified to include support for persistent memory tracking for PMFuzz.
GitHub - Systems-ShiftLab/pmfuzz: A testcase generation tool for Persistent Memory Programs.
A testcase generation tool for Persistent Memory Programs. - GitHub - Systems-ShiftLab/pmfuzz: A testcase generation tool for Persistent Memory Programs.
GitHubSystems-ShiftLab