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
``` @inproceedings{liu2021pmfuzz, title={PMFuzz: Test Case Generation for Persistent Memory Programs}, author={Liu, Sihang and Mahar, Suyash and Ray, Baishakhi and Khan, Samira}, booktitle={Proceedings of the Twenty-sixth International Conference on Architectural Support for Programming Languages and Operating Systems}, year={2021} } ```
Dependencies
PMFuzz was tested using the following environment configuration, other versions may work:
- Ubuntu 18.04
- NDCTL v64 or higher
- libunwind (
libunwind-dev
) - libini-config (
libini-config-dev
) - Python 3.8
- GNUMake >= 3.82
- Kernel version 5.4
- Anaconda or virtualenv (recommended)
For compiling documentation:
- doxygen
- pdflatex
- 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:
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
).
USE_FAKE_MMAP
=(0,1): Enables fake mmap which mounts an image in the volaile memory.PMEM_MMAP_HINT
=<addr>
: Address of the mount point of the pool.ENABLE_CNST_IMG
=(0,1): Disables default PMDK’s behaviour that generates non-identical images for same input.FI_MODE
=(<empty or unset>|IMG_GEN|IMG_REP)
: See libpmfuzz.cFAILURE_LIST
=<path-to-output-file>
: See libpmfuzz.cPMFUZZ_DEBUG
=(0,1): Enables debug output from libpmfuzzENABLE_PM_PATH
: Enables deep paths in PMFuzzGEN_ALL_CS
: Partially disables the probabilistic generation of crash sites and more of them are generated fromlibpmfuzz.c
IMG_CREAT_FINJ
: Disables the probabilistic generation of crash sites and all of them are generated fromlibpmfuzz.c
PMFUZZ_SKIP_TC_CHECK
: Disable testcase size check in AFL++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:
- Preeny (license)
Preeny was modified to fix a bug in desock. All changes are contained in vendor/pathes/preeny_path - AFL++ (license)
AFL++ was modified to include support for persistent memory tracking for PMFuzz.