From patchwork Sat Apr 8 20:58:11 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: David Howells X-Patchwork-Id: 9671277 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id A6F43601EB for ; Sat, 8 Apr 2017 20:58:17 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 95D4C28421 for ; Sat, 8 Apr 2017 20:58:17 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 894C128427; Sat, 8 Apr 2017 20:58:17 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=unavailable version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 22D4128421 for ; Sat, 8 Apr 2017 20:58:17 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752462AbdDHU6P (ORCPT ); Sat, 8 Apr 2017 16:58:15 -0400 Received: from mx1.redhat.com ([209.132.183.28]:48244 "EHLO mx1.redhat.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752427AbdDHU6O (ORCPT ); Sat, 8 Apr 2017 16:58:14 -0400 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 9BA68104D5; Sat, 8 Apr 2017 20:58:13 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com 9BA68104D5 Authentication-Results: ext-mx09.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx09.extmail.prod.ext.phx2.redhat.com; spf=pass smtp.mailfrom=dhowells@redhat.com DKIM-Filter: OpenDKIM Filter v2.11.0 mx1.redhat.com 9BA68104D5 Received: from warthog.procyon.org.uk (ovpn-120-211.rdu2.redhat.com [10.10.120.211]) by smtp.corp.redhat.com (Postfix) with ESMTP id 4AE5497A77; Sat, 8 Apr 2017 20:58:12 +0000 (UTC) Organization: Red Hat UK Ltd. Registered Address: Red Hat UK Ltd, Amberley Place, 107-111 Peascod Street, Windsor, Berkshire, SI4 1TE, United Kingdom. Registered in England and Wales under Company Registration No. 3798903 Subject: [PATCH 3/4] xfstests: Partially expand the documentation [ver #11] From: David Howells To: linux-xfs@vger.kernel.org Cc: hch@infradead.org, amir73il@gmail.com, david@fromorbit.com, fstests@vger.kernel.org, dhowells@redhat.com, linux-fsdevel@vger.kernel.org Date: Sat, 08 Apr 2017 21:58:11 +0100 Message-ID: <149168509161.8932.2664851483762586262.stgit@warthog.procyon.org.uk> In-Reply-To: <149168507699.8932.8909870911625408916.stgit@warthog.procyon.org.uk> References: <149168507699.8932.8909870911625408916.stgit@warthog.procyon.org.uk> User-Agent: StGit/0.17.1-dirty MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.38]); Sat, 08 Apr 2017 20:58:13 +0000 (UTC) Sender: linux-fsdevel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-fsdevel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Partially expand the documentation available in xfstests to include requirements checking and auxiliary programs for testing. Signed-off-by: David Howells Reviewed-by: Darrick J. Wong --- doc/auxiliary-programs.txt | 56 +++++++++++++++++++++++++++++++ doc/requirement-checking.txt | 77 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 133 insertions(+) create mode 100644 doc/auxiliary-programs.txt create mode 100644 doc/requirement-checking.txt diff --git a/doc/auxiliary-programs.txt b/doc/auxiliary-programs.txt new file mode 100644 index 0000000..17797b0 --- /dev/null +++ b/doc/auxiliary-programs.txt @@ -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 "" + + +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 diff --git a/doc/requirement-checking.txt b/doc/requirement-checking.txt new file mode 100644 index 0000000..f3fc9f4 --- /dev/null +++ b/doc/requirement-checking.txt @@ -0,0 +1,77 @@ + ======================================== + 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_ 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 "$NAME_PROG" 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 "KILLALL_PROG" killall + + to locate the killall command and then: + + $KILLALL_PROG -q $FSSTRESS_PROG + + 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 + + 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 [] + + The test requires that the xfs_io command be available, that it supports + command and, optionally, that that command supports the specified + switch. For example: + + _require_xfs_io_command "falloc" + _require_xfs_io_command "chattr" "+/-x" + + The first requires that xfs_io support the falloc command and the second + that it supports the chattr command and that the chattr command supports + the +x and -x arguments (DAX attribute). + + +======================== +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.