From patchwork Tue Apr 4 15:55:25 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: David Howells X-Patchwork-Id: 9661975 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 D471A602B5 for ; Tue, 4 Apr 2017 15:55:33 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id C343B281AA for ; Tue, 4 Apr 2017 15:55:33 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id B83F728307; Tue, 4 Apr 2017 15:55:33 +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 5F52C281AA for ; Tue, 4 Apr 2017 15:55:33 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1754604AbdDDPzc (ORCPT ); Tue, 4 Apr 2017 11:55:32 -0400 Received: from mx1.redhat.com ([209.132.183.28]:18649 "EHLO mx1.redhat.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754573AbdDDPzb (ORCPT ); Tue, 4 Apr 2017 11:55:31 -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 699BC68800; Tue, 4 Apr 2017 15:55:30 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com 699BC68800 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 699BC68800 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 A228D9F369; Tue, 4 Apr 2017 15:55:26 +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 #5] 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: Tue, 04 Apr 2017 16:55:25 +0100 Message-ID: <149132132595.18980.156040870381065105.stgit@warthog.procyon.org.uk> In-Reply-To: <149132130900.18980.537296385250153410.stgit@warthog.procyon.org.uk> References: <149132130900.18980.537296385250153410.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]); Tue, 04 Apr 2017 15:55:30 +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 | 69 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 125 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..29f0b74 --- /dev/null +++ b/doc/requirement-checking.txt @@ -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_ 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.