From patchwork Sun Mar 23 14:18:58 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 3879171 Return-Path: X-Original-To: patchwork-intel-gfx@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.19.201]) by patchwork1.web.kernel.org (Postfix) with ESMTP id BBB259F391 for ; Sun, 23 Mar 2014 14:19:50 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id A76D520263 for ; Sun, 23 Mar 2014 14:19:49 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) by mail.kernel.org (Postfix) with ESMTP id 8D1B0201B4 for ; Sun, 23 Mar 2014 14:19:48 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 0BFA26E67C; Sun, 23 Mar 2014 07:19:48 -0700 (PDT) X-Original-To: intel-gfx@lists.freedesktop.org Delivered-To: intel-gfx@lists.freedesktop.org Received: from mail-ee0-f45.google.com (mail-ee0-f45.google.com [74.125.83.45]) by gabe.freedesktop.org (Postfix) with ESMTP id 2233D6E67C for ; Sun, 23 Mar 2014 07:19:46 -0700 (PDT) Received: by mail-ee0-f45.google.com with SMTP id d17so3475884eek.18 for ; Sun, 23 Mar 2014 07:19:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ffwll.ch; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=PbeDN2PDBPjPIbAek/GcPAE24HQ4OTQl+G8xmnzOvNc=; b=TZR0YPQowZxjX3wmoCkprgKkFEpbJ+t6YoLkbHPv766L3dYpjmTstG6lFtpgO4IT3V m2NViC/dVwiED7PJ6VT5apOjtaF4yXjCTREI879mGPaDBpXTLJnmFAC3K1bUwieJdN/5 tJL+gfsUlqjNaoF1JH7+XLZMSh6DEfapV0JTY= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=PbeDN2PDBPjPIbAek/GcPAE24HQ4OTQl+G8xmnzOvNc=; b=iY1Xr7yxj+9VXcGNv0/ZYZkUAuuxb98peyZCm69Z7yYmpAaNlrYHKUk7QjlO1VN3UD NwUofJ7tiWN84cXljlQ5Gj2462rm5IoWTdur3vCcss3TspNQS29CchKdavZiDEPnmMX6 MqHGA3h8XzFPrnWlxIXznljSkSQNg4LY8d/kpvMcxNen1XML4Cm66B4O47q6HQutOj4S ta2tkzkcjLfKDlKVkPpEJm/7U43yvMDTl7bWKoKVrpIDO1U4B+yVIygX1m/6Y7ZhhF/j lT+JiXTM8S1ZASe+wX4T8fcTA+tmAMRnJXiDidfN5bZnIqdFFVADe5Wu5NDtXS2t8MdQ L2nQ== X-Gm-Message-State: ALoCoQk1+06MXhGNZw4eXA6jdg8frHvcWJ29YMoGAtF8+4BlgLsY7WFCtJwnBMArGSZV7PCpKQDR X-Received: by 10.15.82.132 with SMTP id a4mr9353683eez.47.1395584386417; Sun, 23 Mar 2014 07:19:46 -0700 (PDT) Received: from phenom.ffwll.local (84-73-67-144.dclient.hispeed.ch. [84.73.67.144]) by mx.google.com with ESMTPSA id cb5sm26392589eeb.18.2014.03.23.07.19.45 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Sun, 23 Mar 2014 07:19:45 -0700 (PDT) From: Daniel Vetter To: Intel Graphics Development Date: Sun, 23 Mar 2014 15:18:58 +0100 Message-Id: <1395584342-11812-25-git-send-email-daniel.vetter@ffwll.ch> X-Mailer: git-send-email 1.8.5.2 In-Reply-To: <1395584342-11812-1-git-send-email-daniel.vetter@ffwll.ch> References: <1395584342-11812-1-git-send-email-daniel.vetter@ffwll.ch> Cc: Daniel Vetter Subject: [Intel-gfx] [PATCH 24/28] lib/igt_aux: api documentation X-BeenThere: intel-gfx@lists.freedesktop.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: Intel graphics driver community testing & development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: intel-gfx-bounces@lists.freedesktop.org Sender: "Intel-gfx" X-Spam-Status: No, score=-4.6 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_MED,RP_MATCHES_RCVD,T_DKIM_INVALID,UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP I'm not really happy with the name of the igt_env_set function, I'll follow up with a patch to change it. Signed-off-by: Daniel Vetter --- .../intel-gpu-tools/intel-gpu-tools-docs.xml | 1 + lib/igt_aux.c | 129 ++++++++++++++++++++- lib/intel_os.c | 12 ++ 3 files changed, 139 insertions(+), 3 deletions(-) diff --git a/docs/reference/intel-gpu-tools/intel-gpu-tools-docs.xml b/docs/reference/intel-gpu-tools/intel-gpu-tools-docs.xml index bf196f27dfd4..bd8294e5fd1e 100644 --- a/docs/reference/intel-gpu-tools/intel-gpu-tools-docs.xml +++ b/docs/reference/intel-gpu-tools/intel-gpu-tools-docs.xml @@ -20,6 +20,7 @@ + diff --git a/lib/igt_aux.c b/lib/igt_aux.c index fff5f0e89387..177f52da53f7 100644 --- a/lib/igt_aux.c +++ b/lib/igt_aux.c @@ -59,6 +59,17 @@ #include "ioctl_wrappers.h" +/** + * SECTION:igt_aux + * @short_description: Auxiliary libararies and support functions + * @title: i-g-t aux + * + * > #include "igt_aux.h" + * + * This library provides various auxiliary helper functions that don't really + * fit into any other topic. + */ + /* signal interrupt helpers */ static struct igt_helper_process signal_helper; @@ -78,6 +89,20 @@ static void sig_handler(int i) sig_stat++; } +/** + * igt_fork_signal_helper: + * + * Fork a child process using #igt_fork_helper to interrupt the parent process + * with a SIGUSR1 signal at regular quick intervals. The corresponding dummy + * signal handler is installed in the parent process. + * + * This is useful to exercise ioctl error paths, at least where those can be + * exercises by interrupting blocking waits, like stalling for the gpu. This + * helper can also be used from children spawned with #igt_fork. + * + * In tests with subtests this function can be called outside of failure + * catching code blocks like #igt_fixture or #igt_subtest. + */ void igt_fork_signal_helper(void) { if (igt_only_list_subtests()) @@ -90,6 +115,14 @@ void igt_fork_signal_helper(void) } } +/** + * igt_stop_signal_helper: + * + * Stops the child process spawned with igt_fork_signal_helper() again. + * + * In tests with subtests this function can be called outside of failure + * catching code blocks like #igt_fixture or #igt_subtest. + */ void igt_stop_signal_helper(void) { if (igt_only_list_subtests()) @@ -100,6 +133,17 @@ void igt_stop_signal_helper(void) sig_stat = 0; } +/** + * igt_env_set: + * @env_var: environment variable name + * @default_value: default value for the environment variable + * + * This function should be used to parse boolean environment variable options. + * + * Returns: + * The boolean value of the environment variable @env_var as decoded by atoi() + * if it is set and @default_value if the variable is not set. + */ bool igt_env_set(const char *env_var, bool default_value) { char *val; @@ -111,6 +155,13 @@ bool igt_env_set(const char *env_var, bool default_value) return atoi(val) != 0; } +/** + * igt_aub_dump_enabled: + * + * Returns: + * True if AUB dumping is enabled with IGT_DUMP_AUB=1 in the environment, false + * otherwise. + */ bool igt_aub_dump_enabled(void) { static int dump_aub = -1; @@ -122,6 +173,15 @@ bool igt_aub_dump_enabled(void) } /* other helpers */ +/** + * igt_exchange_int: + * @array: pointer to the array of integers + * @i: first position + * @j: second position + * + * Exchanges the two values at array indices @i and @j. Useful as an exchange + * function for igt_permute_array(). + */ void igt_exchange_int(void *array, unsigned i, unsigned j) { int *int_arr, tmp; @@ -132,10 +192,20 @@ void igt_exchange_int(void *array, unsigned i, unsigned j) int_arr[j] = tmp; } +/** + * igt_permute_array: + * @array: pointer to array + * @size: size of the array + * @exchange_func: function to exchange array elements + * + * This function randomly permutes the array using random() as the PRNG source. + * The @exchange_func function is called to exchange two elements in the array + * when needed. + */ void igt_permute_array(void *array, unsigned size, - void (*exchange_func)(void *array, - unsigned i, - unsigned j)) + void (*exchange_func)(void *array, + unsigned i, + unsigned j)) { int i; @@ -147,6 +217,17 @@ void igt_permute_array(void *array, unsigned size, } } +/** + * igt_progress: + * @header: header string to prepend to the progress indicator + * @i: work processed thus far + * @total: total amount of work + * + * This function draws a progress indicator, which is useful for running + * long-winded tests manually on the console. To avoid spamming logfiles in + * automated runs the progress indicator is supressed when not running on a + * terminal. + */ void igt_progress(const char *header, uint64_t i, uint64_t total) { int divider = 200; @@ -173,6 +254,13 @@ void igt_progress(const char *header, uint64_t i, uint64_t total) drm_intel_bo **trash_bos; int num_trash_bos; +/** + * igt_init_aperture_trashers: + * @bufmgr: libdrm buffer manager + * + * Initialize the aperture trasher using @bufmgr, which can then be run with + * igt_trash_aperture(). + */ void igt_init_aperture_trashers(drm_intel_bufmgr *bufmgr) { int i; @@ -186,6 +274,11 @@ void igt_init_aperture_trashers(drm_intel_bufmgr *bufmgr) trash_bos[i] = drm_intel_bo_alloc(bufmgr, "trash bo", 1024*1024, 4096); } +/** + * igt_trash_aperture: + * + * Trash the aperture by walking a set of GTT memory mapped objects. + */ void igt_trash_aperture(void) { int i; @@ -199,6 +292,11 @@ void igt_trash_aperture(void) } } +/** + * igt_cleanup_aperture_trashers: + * + * Clean up all aperture trasher state set up with igt_init_aperture_trashers(). + */ void igt_cleanup_aperture_trashers(void) { int i; @@ -209,6 +307,14 @@ void igt_cleanup_aperture_trashers(void) free(trash_bos); } +/** + * igt_system_suspend_autoresume: + * + * Execute a system suspend-to-mem cycle and automatically wake up again using + * the firmwares resume timer. + * + * This is very handy for implementing any kind of suspend/resume test. + */ void igt_system_suspend_autoresume(void) { int ret; @@ -222,6 +328,14 @@ void igt_system_suspend_autoresume(void) igt_assert(ret == 0); } +/** + * igt_drop_roo: + * + * Drop root priviledges and make sure it actually worked. Useful for tests + * which need to check security constraints. Note that this should only be + * called from manually forked processes, since the lack of root priviledges + * will wreak havoc with the automatic cleanup handlers. + */ void igt_drop_root(void) { igt_assert(getuid() == 0); @@ -233,6 +347,15 @@ void igt_drop_root(void) igt_assert(getuid() == 2); } +/** + * igt_wait_for_keypress: + * + * Waits for a key press when run interactively. When not connected to a + * terminal immediately continues. + * + * This is useful for display tests where under certain situation manual + * inspection of the display is useful. + */ void igt_wait_for_keypress(void) { struct termios oldt, newt; diff --git a/lib/intel_os.c b/lib/intel_os.c index 3a7397aa986a..fb9f19cb5052 100644 --- a/lib/intel_os.c +++ b/lib/intel_os.c @@ -51,6 +51,12 @@ #include "drmtest.h" #include "igt_aux.h" +/** + * intel_get_total_ram_mb: + * + * Returns: + * The total amount of system RAM available in MB. + */ uint64_t intel_get_total_ram_mb(void) { @@ -79,6 +85,12 @@ intel_get_total_ram_mb(void) return retval / (1024*1024); } +/** + * intel_get_total_swap_mb: + * + * Returns: + * The total amount of swap space available in MB. + */ uint64_t intel_get_total_swap_mb(void) {