OPAE Testing Framework
Objective
The main goal of the testing framework used by OPAE is to enable (Google test) tests that don't require the presence of either an OPAE kernel driver or an OPAE compatible FPGA. An additional goal is to allow authoring tests that can easily ported from a mock environment to a real system.
Mocking the Kernel Driver
The two interfaces to the OPAE Linux driver are ioctl calls and sysfs
files. The OPAE C library uses both of these interfaces in its implementation
to control and/or query the device. To test the API functions (including
internal functions used within), a mock driver has been developed that can
allow for calling these functions without calling the kernel driver through
these interfaces. At a high level, system calls related to ioctl and sysfs
files (eg. ioctl, open) are implemented in a C file called mock.c which
in turn calls into a C++ singleton class called test_system using its C
interface. This C++ singleton can also be used by any google test code to call
any necessary setup and teardown routines. When calls such as open are called
and handled by test_system, paths used by the OPAE kernel driver
(/dev/intel-fpga-port.0 or /sys/class/fpga/intel-fpga-port.0) can be
re-rooted to point to files in a mock sysfs subtree.
The following diagram illustrate a general flow of a google test using the mock
driver and the test_system.
test_system
As mentioned above, test_system is a singleton class that is designed to be
called from either C code (by using its C interface) or by using its C++
instance() function. This allows it to be called from both google test tests
as well as from C functions that are being mocked. Tests that depend on any
sysfs paths handled by the OPAE kernel driver should be implemented as part of
a test fixture. This fixture should call test_system::initialize in its setup
and should also call test_system::finalize in its teardown. If a unit test
does not depend on any sysfs paths used by the OPAE kernel driver, then there
is no need to call these two functions and those functions should be
implemented without a fixture. The class test_system is compiled into a
shared library (libtest_system.so) and should be linked with any OPAE test
that uses it. Additionally, the file mock.c is not included in this library
and should be included into any test executable that uses test_system.
ioctl handlers
The file ioctl_handlers.cpp includes some default ioctl handler functions for
most of the ioctl requests (as identified by the request constant in
intel-fpga.h). This file calls the function
test_system::register_ioctl_handler which maps a request constant to a
function that should be called when the request is made. A templated function,
dummy_ioctl is provided to allow registering an ioctl handler that uses its
template arguments to define what to return from ioctl and also to specify what
errno should be set to. This is intended for authoring negative tests that
depend on ioctl calls.