Lustre Kernel configure checks

Configure tests for Lustre kernel api headers and functions are used to support building against a wide range of kernels. Configure tests should follow the style guildlines

Parallel build checks should be independent of other tests and not rely on the results from other tests that are run in the same pass. Most tests can and should be written to use the parallel checking infrastructure.

Serial tests are expensive and run earlier than the parallel tests so the results of these tests can be used after they are invoked.

A few parallel tests are run early (See: config/lustre-build.m4 LB2_LINUX_TEST_COMPILE_ALL([early]) with the remaining parallel tests being run in a single final pass.

Serial tests are straight forward compile tests, if you need extra compile flags (ex: -Werror), includes or module symbols the associated environment variables need to be saved and modified before the test and restored afterword.

Parallel test macros provide a few options for test setup that remain captured in the generated Makefile and test sources. This can be useful when debugging a test. The generated parallel tests can be retained with by setting the environment variable PARALLEL_BUILD_OPT to 'debug' before configure is run:

export PARALLEL_BUILD_OPT=debug
./configure --config-cache --enable-server --enable-client --with-linux=/usr/src/kernels/5.14.0-284.31.1.ldiskfs.el9.x86_64 --enable-modules

The resulting configure test can be found in a directory under _lpb and following the assocated Makefile it can be examined, run and modified iteratively to refine the source and options needed.

For the casual developer the number of LB_CHECK_COMPILE and parallel LB2_LINUX_TEST_SRC and LB2_MSG_LINUX_TEST_RESULT pairs should be sufficient to perform cut-paste-modify without serious confusion or complication.

In addition there a some specialized checks:

• For kernel CONFIG_<value> options: LB2_SRC_CHECK_CONFIG and LB2_TEST_CHECK_CONFIG
• For kernel CONFIG_<value> *or* CONFIG_<value>_MODULE_ options: LB2_SRC_CHECK_CONFIG_IM and LB2_TEST_CHECK_CONFIG_IM
• For kernel headers: LB2_CHECK_LINUX_HEADER_SRC and LB2_CHECK_LINUX_HEADER_RESULT
• For LNet in-kernel and mofed: LB2_OFED_TEST_SRC and LB2_OFED_TEST_RESULTS used to generate nearly duplicate tests that have differing environments.

When writing tests the preference is to prefer a positive statement that has the effect of setting a define on success (this is mandatory for OFED tests).

LB2_LINUX_TEST_SRC([unique_id],[source_global],[source_code],[extra_cflags]
                   [extra_includes],[symbol],[special])

Where:

• unique_id: is shared between the SRC and RESULT and is also used to create the directory structure in which the sources are written.
• source_global: is generally the '#include' and any minimal module level boiler plate needed for source_code
• source_code: is the legal code that if it compiles (and optional generates a .ko module) the 'on_success' will be run, otherwise 'on_failure' will be run
• extra_cflags: often set to -Werror or left empty.
• extra_includes: usually left empty, used by O2IB macros.
• symbol: Used to force a kernel symbol Ex: LB_SRC_LDISKFSFS_DIRHASH_WANTS_DIR
• special: leave blank, used by O2IB macros.

LB2_MSG_LINUX_TEST_RESULT([if_message],[unique_id],[on_success],[on_failure],[module])

Where:

• if_message: configure message for this test preferably of the form 'if function() exists'
• unique_id: the SRC that this check is for
• on_success: the snippet that will be run if the compile succeeded, usually an AC_DEFINE() macro.
• on_failure: the snippet that will be run if the compile failed.
• module: the text 'module' if the compile *must* produce a kernel object (aka link successfully). Used for tests that check if a kernel symbol is exported.

LB2_SRC_CHECK_CONFIG([value])
LB2_SRC_CHECK_CONFIG_IM([value])
LB2_TEST_CHECK_CONFIG([value],[on_success],[on_failure])
LB2_TEST_CHECK_CONFIG_IM([value],[on_success],[on_failure])

Where:

• value: is kernel config macro without the preceding CONFIG_ [or post _MODULE]
• on_success: the snippet that will be run if the compile succeeded.
• on_failure: the snippet that will be run if the compile failed.

LB2_CHECK_LINUX_HEADER_SRC([include],[extra_cflags])
LB2_CHECK_LINUX_HEADER_RESULT([include],[on_success],[on_failure])

Where:

• include: the include file, also shared between the SRC and RESULT
• extra_cflags: usually set to -Werror and can be left empty.
• on_success: the snippet that will be run if the compile succeeded.
• on_failure: the snippet that will be run if the compile failed.

LB2_OFED_TEST_SRC([unique_id],[source_global],[source_code],[extra_cflags]
                   [extra_includes])

Where:

• unique_id: is shared between the SRC and RESULT and is also used to create the directory structure in which the sources are written.
• source_global: is generally the '#include' and any minimal module level boiler plate needed for source_code
• source_code: is the legal code that if it compiles (and optional generates a .ko module) the 'on_success' will be run, otherwise 'on_failure' will be run
• extra_cflags: often set to -Werror or left empty.
• extra_includes: Used for MOFED build

LB2_OFED_TEST_RESULTS([if_message],[unique_id],[defined_on_success])

Where:

• if_message: configure message for this test preferably of the form 'if function() exists'
• unique_id: the SRC that this check is paired with
• defined_on_success: Must start with HAVE_OFED_ and if the MOFED compile succeeded HAVE_OFED_<something> will be defined. And if the in-kernel compile succeeded IN_KERNEL_HAVE_OFED_<something> will be defined