new file mode 100644
@@ -0,0 +1,56 @@
+ ==============================
+ AUXILIARY PROGRAMS FOR TESTING
+ ==============================
+
+Not everything a test script can do is easily done within a test script;
+sometimes it makes a lot more sense to write auxiliary program in C and have
+the test script call them. Auxiliary commands can be found in the src/
+directory and in other packages.
+
+Tests wanting to use an auxiliary program found in the src/ directory should
+note the dependency with:
+
+ _require_test_program "<program-name>"
+
+
+Contents:
+
+ - af_unix -- Create an AF_UNIX socket
+ - stat_test -- statx syscall exercise
+ - xfs_io -- General I/O operation exercise
+
+
+==================
+QUICK DESCRIPTIONS
+==================
+
+af_unix
+
+ The af_unix program creates an AF_UNIX socket at the given location.
+
+stat_test
+
+ The stat_test program is primarily designed to exercise the statx()
+ system call. It can check statx() against fstatat() and it can
+ compare and check various file attributes.
+
+ See also:
+ _require_statx
+
+
+xfs_io
+
+ The xfs_io program can be found in the xfsprogs package and can be used
+ to perform sequences of I/O commands, though it is limited to what it
+ can do on open files.
+
+ xfs_io is a debugging tool that is aimed at examining regular file I/O
+ paths rather than a raw XFS volume itself. These code paths include
+ not only the obvious read/write/mmap interfaces for manipulating files,
+ but also cover all of the XFS extensions (such as space preallocation,
+ additional inode flags, etc).
+
+ Most of its commands can also be used with other filesystems.
+
+ See also:
+ _require_xfs_io_command
new file mode 100644
@@ -0,0 +1,69 @@
+ ========================================
+ TESTING FOR REQUIREMENTS IN TEST SCRIPTS
+ ========================================
+
+Test scripts need to indicate to the infrastructure what sorts of requirements
+they have. This is done with _require_<xxx> macros, which may take parameters.
+
+ (1) General requirements.
+
+ _require_command
+ _require_test
+ _require_test_program
+ _require_xfs_io_command
+
+ (2) System call requirements.
+
+ _require_statx
+
+
+====================
+GENERAL REQUIREMENTS
+====================
+
+_require_command "$VAR" name
+
+ The test requires an external command, called 'name' be present on the
+ system and that '$VAR' should be set with the path to that command. $VAR
+ should then be used to refer to the command when executing it. For
+ example:
+
+ _require_command "$NC_PROG" "nc"
+
+ to locate the netcat command and then:
+
+ $NC_PROG -U -l $TEST_DIR/$seq-sock
+
+ to make use of it.
+
+
+_require_test
+
+ The test requires that the block device specified by $TEST_DEV be mounted
+ on $TEST_DIR.
+
+
+_require_test_program "name"
+
+ The test requires a program by the name of 'name' be present and built in
+ the src/ directory. For example:
+
+ _require_test_program "stat_test"
+
+ requires that src/stat_test be built.
+
+
+_require_xfs_io_command "falloc"
+
+ The test requires that the xfs_io command be available and that it support
+ the 'falloc' command.
+
+
+========================
+SYSTEM CALL REQUIREMENTS
+========================
+
+_require_statx
+
+ The test requires the use of the statx() system call and will be skipped
+ if it isn't available in the kernel.
Partially expand the documentation available in xfstests to include requirements checking and auxiliary programs for testing. Signed-off-by: David Howells <dhowells@redhat.com> --- doc/auxiliary-programs.txt | 56 ++++++++++++++++++++++++++++++++++ doc/requirement-checking.txt | 69 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 125 insertions(+) create mode 100644 doc/auxiliary-programs.txt create mode 100644 doc/requirement-checking.txt