At this early stage we are not yet distributing famfs in package-manager bundles (e.g. rpm, deb). The famfs kernel module has been submitted to the Linux community as an RFC. The steps to test famfs are as follows:
- Install prerequisites
- Build and install a kernel with the famfs patches
- Build the famfs user space (this repo)
- Configure one or more real or simulated dax or pmem devices
- Run the famfs tests
- Create and use a famfs file system
- Profit!!
On fedora, you probably need to install the following, at minimum
sudo dnf groupinstall "Development Tools"
sudo dnf install kernel-devel
sudo dnf install cmake
sudo dnf install g++
sudo dnf install libuuid-devel
sudo dnf install daxctl ndctl
sudo dnf install gcovr
Pay attention to error messages when you build, new dependencies may arise later, and different kernel installations may have different missing dependencies.
sudo apt install build-essential
sudo apt install cmake
sudo apt install uuid-dev
sudo apt install zlib1g-dev
sudo apt install daxctl ndctl
sudo apt install gcovr
Pay attention to error messages when you build, new dependencies may arise later, and different kernel installations may have different missing dependencies.
From the top level directory:
make clean all
The first time through keep in mind that you might need to resolve dependencies to get it to run.
You must load the kernel module in order to use famfs
sudo modprobe famfs
Famfs does not have packaged installation files yet, once you have built it, you can install the user space library and cli with the following command:
sudo make install
In order to run famfs you need or a devdax device (e.g. /dev/dax0.0). To run in a shared mode, you need more than one system that shares a memory device.
/dev/pmem devices was deprecated, and the default device was changed to /dev/dax0.0. If you are using the v1 kernel patch set you can still override and use a pmem device, but the famfs v2 patch set will remove pmem support. If you are using pmem devices, they can be converted to devdax mode via ndctl.
Gory details for setting up virtual machines and virtual dax and pmem devices are in the Configuring Virtual Machines for famfs documentation.
Famfs already has a substantial set of tests, though we plan to expand them substantially (and we would love your help with that!).
The famfs smoke tests load the kernel module, create and mount a famfs file system, and test its functionality. The smoke tests currently must be run by a non-privileged user with passwordless sudo enabled. Running the tests as root does not work, because they expect certain operations to fail due to non-root privileges.
You can enable passwordless sudo for user 'fred' in your test systems and VMs as follows:
# Substitute your username for "fred", and run this command as root
echo "fred ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/fred
sudo make smoke), it it will not work correctly because the smoke tests expect to be running as a non-privileged user except when the smoke tests invoke sudo.
If you have already successfully built famfs and configured a pmem device, you can run smoke tests as follows:
make smoke
You can also optionally specify the device and mount point as environment variables when running smoke tests
DEV=/dev/dax1.0 MPT=/mnt/famfs make smoke
or, if you're running tcsh or csh shells:
env DEV=/dev/dax1.0 MPT=/mnt/famfs make smoke
You can see an example of the full output from run_smoke.sh here
The smoke tests (by default) require the following:
- A valid /dev/dax0.0 device which is at least 4GiB in size
Famfs uses the googletest framework for unit testing code components, although test coverage is still limited.
make test
You can also do this:
sudo debug/test/famfs_unit_tests
Important note: the unit tests must be run as root or under sudo, primarily because getting the system UUID only works as root. We may look into circumventing this...
You can run the smoke tests under valgrind as follows:
DEV=/dev/dax1.0 make smoke_valgrind
If the smoke tests complete and valgrind finds no errors, you will see a message such as this:
Congratulations: no errors found by Valgrind
Otherwise, you will see the valgrind output from just the tests where valgrind found problems.
To build for coverage tests, do the following in user:
make clean coverage
DEV=/dev/dax1.0 make coverage_test
firefox coverage/famfs_unit_coverage/index.html # or any other browser
The resulting report looks like this as of early 2024.
This is the combined coverage from smoke and unit tests.