{"id":2225757,"url":"http://patchwork.ozlabs.org/api/patches/2225757/?format=json","web_url":"http://patchwork.ozlabs.org/project/ltp/patch/20260421144126.613547-1-pvorel@suse.cz/","project":{"id":59,"url":"http://patchwork.ozlabs.org/api/projects/59/?format=json","name":"Linux Test Project development","link_name":"ltp","list_id":"ltp.lists.linux.it","list_email":"ltp@lists.linux.it","web_url":"","scm_url":"","webscm_url":"","list_archive_url":"","list_archive_url_format":"","commit_url_format":""},"msgid":"<20260421144126.613547-1-pvorel@suse.cz>","list_archive_url":null,"date":"2026-04-21T14:41:26","name":"[v2,1/1] tst_test.h: Convert rest of doc to kerneldoc","commit_ref":null,"pull_url":null,"state":"needs-review-ack","archived":false,"hash":"7c2b970c19205f3a1023b2a8e530af03a2e80195","submitter":{"id":70792,"url":"http://patchwork.ozlabs.org/api/people/70792/?format=json","name":"Petr Vorel","email":"pvorel@suse.cz"},"delegate":null,"mbox":"http://patchwork.ozlabs.org/project/ltp/patch/20260421144126.613547-1-pvorel@suse.cz/mbox/","series":[{"id":500824,"url":"http://patchwork.ozlabs.org/api/series/500824/?format=json","web_url":"http://patchwork.ozlabs.org/project/ltp/list/?series=500824","date":"2026-04-21T14:41:26","name":"[v2,1/1] tst_test.h: Convert rest of doc to kerneldoc","version":2,"mbox":"http://patchwork.ozlabs.org/series/500824/mbox/"}],"comments":"http://patchwork.ozlabs.org/api/patches/2225757/comments/","check":"warning","checks":"http://patchwork.ozlabs.org/api/patches/2225757/checks/","tags":{},"related":[],"headers":{"Return-Path":"","X-Original-To":["incoming@patchwork.ozlabs.org","ltp@lists.linux.it"],"Delivered-To":["patchwork-incoming@legolas.ozlabs.org","ltp@picard.linux.it"],"Authentication-Results":["legolas.ozlabs.org;\n\tdkim=fail reason=\"signature verification failed\" (1024-bit key;\n unprotected) header.d=suse.cz header.i=@suse.cz header.a=rsa-sha256\n header.s=susede2_rsa header.b=v1stmGh4;\n\tdkim=fail reason=\"signature verification failed\" header.d=suse.cz\n header.i=@suse.cz header.a=ed25519-sha256 header.s=susede2_ed25519\n header.b=gUau17rz;\n\tdkim=fail reason=\"signature verification failed\" (1024-bit key)\n header.d=suse.cz header.i=@suse.cz header.a=rsa-sha256 header.s=susede2_rsa\n header.b=v1stmGh4;\n\tdkim=neutral header.d=suse.cz header.i=@suse.cz header.a=ed25519-sha256\n header.s=susede2_ed25519 header.b=gUau17rz;\n\tdkim-atps=neutral","legolas.ozlabs.org;\n spf=pass (sender SPF authorized) smtp.mailfrom=lists.linux.it\n (client-ip=2001:1418:10:5::2; helo=picard.linux.it;\n envelope-from=ltp-bounces+incoming=patchwork.ozlabs.org@lists.linux.it;\n receiver=patchwork.ozlabs.org)","smtp-out2.suse.de;\n dkim=pass header.d=suse.cz header.s=susede2_rsa header.b=v1stmGh4;\n dkim=pass header.d=suse.cz header.s=susede2_ed25519 header.b=gUau17rz"],"Received":["from picard.linux.it (picard.linux.it [IPv6:2001:1418:10:5::2])\n\t(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)\n\t key-exchange x25519 server-signature ECDSA (secp384r1) server-digest SHA384)\n\t(No client certificate requested)\n\tby legolas.ozlabs.org (Postfix) with ESMTPS id 4g0Q6G4G43z1yCv\n\tfor ; Wed, 22 Apr 2026 00:41:42 +1000 (AEST)","from picard.linux.it (localhost [IPv6:::1])\n\tby picard.linux.it (Postfix) with ESMTP id 4DCB33E4A89\n\tfor ; Tue, 21 Apr 2026 16:41:40 +0200 (CEST)","from in-7.smtp.seeweb.it (in-7.smtp.seeweb.it\n [IPv6:2001:4b78:1:20::7])\n (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)\n key-exchange X25519 server-signature ECDSA (secp384r1) server-digest SHA384)\n (No client certificate requested)\n by picard.linux.it (Postfix) with ESMTPS id 8C4B03E1B27\n for ; Tue, 21 Apr 2026 16:41:36 +0200 (CEST)","from smtp-out2.suse.de (smtp-out2.suse.de [195.135.223.131])\n (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)\n key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest\n SHA256)\n (No client certificate requested)\n by in-7.smtp.seeweb.it (Postfix) with ESMTPS id 0A47F200B73\n for ; Tue, 21 Apr 2026 16:41:35 +0200 (CEST)","from imap1.dmz-prg2.suse.org (imap1.dmz-prg2.suse.org\n [IPv6:2a07:de40:b281:104:10:150:64:97])\n (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)\n key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest\n SHA256)\n (No client certificate requested)\n by smtp-out2.suse.de (Postfix) with ESMTPS id 57BAE5BCEE;\n Tue, 21 Apr 2026 14:41:35 +0000 (UTC)","from imap1.dmz-prg2.suse.org (localhost [127.0.0.1])\n (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)\n key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest\n SHA256)\n (No client certificate requested)\n by imap1.dmz-prg2.suse.org (Postfix) with ESMTPS id 31086593AF;\n Tue, 21 Apr 2026 14:41:35 +0000 (UTC)","from dovecot-director2.suse.de ([2a07:de40:b281:106:10:150:64:167])\n by imap1.dmz-prg2.suse.org with ESMTPSA id eWlpCp+M52lHVwAAD6G6ig\n (envelope-from ); Tue, 21 Apr 2026 14:41:35 +0000"],"DKIM-Signature":["v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz;\n s=susede2_rsa;\n t=1776782495;\n h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc:\n mime-version:mime-version:\n content-transfer-encoding:content-transfer-encoding;\n bh=TqICN6pRz+DqXQaMdSbW2KQPkn7qemNxDNt6witJjxM=;\n b=v1stmGh4blL+T0DOb1mHWEcw9Tfpa92w9x9yYPgJ2bCA6xaRzk3ed6a3w5vFQUbxXBYIAL\n MM/CNWeJ3qp10/c+ApCmLXyIyTbtAISoE5oqa7HnXMMkijrtr3ViEoLBSa0czlX/EXZdf0\n 07WNr7qTz6GkiJcfjpAj1657+so+iUc=","v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz;\n s=susede2_ed25519; t=1776782495;\n h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc:\n mime-version:mime-version:\n content-transfer-encoding:content-transfer-encoding;\n bh=TqICN6pRz+DqXQaMdSbW2KQPkn7qemNxDNt6witJjxM=;\n b=gUau17rz7dfpu+xjjyeNPRwAs/k3lhhgtUnMpQOrkVJUjZd1Qutemg/PhBHFS3txTiOZ3Z\n 2ZImgVAQQmB6nRBg==","v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz;\n s=susede2_rsa;\n t=1776782495;\n h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc:\n mime-version:mime-version:\n content-transfer-encoding:content-transfer-encoding;\n bh=TqICN6pRz+DqXQaMdSbW2KQPkn7qemNxDNt6witJjxM=;\n b=v1stmGh4blL+T0DOb1mHWEcw9Tfpa92w9x9yYPgJ2bCA6xaRzk3ed6a3w5vFQUbxXBYIAL\n MM/CNWeJ3qp10/c+ApCmLXyIyTbtAISoE5oqa7HnXMMkijrtr3ViEoLBSa0czlX/EXZdf0\n 07WNr7qTz6GkiJcfjpAj1657+so+iUc=","v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz;\n s=susede2_ed25519; t=1776782495;\n h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc:\n mime-version:mime-version:\n content-transfer-encoding:content-transfer-encoding;\n bh=TqICN6pRz+DqXQaMdSbW2KQPkn7qemNxDNt6witJjxM=;\n b=gUau17rz7dfpu+xjjyeNPRwAs/k3lhhgtUnMpQOrkVJUjZd1Qutemg/PhBHFS3txTiOZ3Z\n 2ZImgVAQQmB6nRBg=="],"From":"Petr Vorel ","To":"ltp@lists.linux.it","Date":"Tue, 21 Apr 2026 16:41:26 +0200","Message-ID":"<20260421144126.613547-1-pvorel@suse.cz>","X-Mailer":"git-send-email 2.53.0","MIME-Version":"1.0","X-Rspamd-Action":"no action","X-Rspamd-Server":"rspamd2.dmz-prg2.suse.org","X-Spamd-Result":"default: False [-3.01 / 50.00]; BAYES_HAM(-3.00)[100.00%];\n MID_CONTAINS_FROM(1.00)[]; NEURAL_HAM_LONG(-1.00)[-1.000];\n R_MISSING_CHARSET(0.50)[];\n R_DKIM_ALLOW(-0.20)[suse.cz:s=susede2_rsa,suse.cz:s=susede2_ed25519];\n NEURAL_HAM_SHORT(-0.20)[-1.000]; MIME_GOOD(-0.10)[text/plain];\n MX_GOOD(-0.01)[]; FUZZY_RATELIMITED(0.00)[rspamd.com];\n MIME_TRACE(0.00)[0:+]; RCVD_VIA_SMTP_AUTH(0.00)[];\n SPAMHAUS_XBL(0.00)[2a07:de40:b281:104:10:150:64:97:from];\n TO_DN_SOME(0.00)[]; ARC_NA(0.00)[];\n DKIM_SIGNED(0.00)[suse.cz:s=susede2_rsa,suse.cz:s=susede2_ed25519];\n RCPT_COUNT_THREE(0.00)[3]; FROM_EQ_ENVFROM(0.00)[];\n FROM_HAS_DN(0.00)[];\n DBL_BLOCKED_OPENRESOLVER(0.00)[suse.cz:dkim,suse.cz:mid,suse.cz:email,imap1.dmz-prg2.suse.org:helo,imap1.dmz-prg2.suse.org:rdns];\n RCVD_COUNT_TWO(0.00)[2]; TO_MATCH_ENVRCPT_ALL(0.00)[];\n DKIM_TRACE(0.00)[suse.cz:+];\n URIBL_BLOCKED(0.00)[imap1.dmz-prg2.suse.org:helo,imap1.dmz-prg2.suse.org:rdns,suse.cz:dkim,suse.cz:mid,suse.cz:email,ozlabs.org:url];\n RCVD_TLS_ALL(0.00)[]","X-Rspamd-Queue-Id":"57BAE5BCEE","X-Spam-Score":"-3.01","X-Spam-Level":"","X-Spam-Status":"No, score=0.1 required=7.0 tests=DKIM_SIGNED,DKIM_VALID,\n DKIM_VALID_AU,DKIM_VALID_EF,SPF_HELO_NONE,SPF_PASS shortcircuit=no\n autolearn=disabled version=4.0.1","X-Spam-Checker-Version":"SpamAssassin 4.0.1 (2024-03-25) on in-7.smtp.seeweb.it","X-Virus-Scanned":"clamav-milter 1.0.9 at in-7.smtp.seeweb.it","X-Virus-Status":"Clean","Subject":"[LTP] [PATCH v2 1/1] tst_test.h: Convert rest of doc to kerneldoc","X-BeenThere":"ltp@lists.linux.it","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"Linux Test Project ","List-Unsubscribe":",\n ","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n ","Content-Type":"text/plain; charset=\"us-ascii\"","Content-Transfer-Encoding":"7bit","Errors-To":"ltp-bounces+incoming=patchwork.ozlabs.org@lists.linux.it","Sender":"\"ltp\" "},"content":"Signed-off-by: Petr Vorel \n---\nChanges in v2:\n* Hopefully address all Cyril's comments in v1. @Cyril if not, please\n fix it and merge under your SOB, it's mostly your text anyway.\n* Describe also tst_remaining_runtime() (that changes\n tst_remaining_runtime() mentioned in struct tst_test members clickable)\n\nLink to v1:\nhttps://lore.kernel.org/ltp/20260421143200.GA611911@pevik/T/#t\nhttps://patchwork.ozlabs.org/project/ltp/patch/20260325120629.113245-1-pvorel@suse.cz/\n\n include/tst_test.h | 89 +++++++++++++++++++++++++++++++++++++---------\n 1 file changed, 72 insertions(+), 17 deletions(-)","diff":"diff --git a/include/tst_test.h b/include/tst_test.h\nindex f12c59f393..c547037ccd 100644\n--- a/include/tst_test.h\n+++ b/include/tst_test.h\n@@ -696,35 +696,87 @@ void tst_reinit(void);\n */\n int tst_run_script(const char *script_name, char *const params[]);\n \n-/*\n- * Sets entire timeout in seconds.\n+/**\n+ * tst_set_timeout() - Sets the timeout part of the overall timeout.\n+ *\n+ * Allows to set the overall timeout dynamically during the test setup phase.\n+ *\n+ * This is used only for rare cases that the test does something that runs for a\n+ * long time and cannot be easily interrupted (otherwise it would set\n+ * :c:type:`.runtime ` and exit when runtime was exhausted).\n+ *\n+ * @timeout: A timeout in seconds, defines the total time allowed for a single\n+ * test iteration, including the setup, runtime, and teardown phases.\n */\n void tst_set_timeout(int timeout);\n \n+/**\n+ * tst_multiply_timeout() - Uses heuristics to multiply a time interval based on\n+ * expected CPU slowdowns.\n+ *\n+ * If a machine is expected to be running slow for some reason a user can export\n+ * :doc:`LTP_TIMEOUT_MUL <../users/setup_tests>` variable that is used by this\n+ * call to multiply the interval.\n+ *\n+ * Various kernel configuration (debugging) options that slow down the machine\n+ * are also attempted to be detected and are taken into account.\n+ *\n+ * @timeout: A timeout.\n+ *\n+ * Return: timeout multiplied with LTP_TIMEOUT_MUL environment variable.\n+ */\n unsigned int tst_multiply_timeout(unsigned int timeout);\n \n-/*\n- * Returns remaining test runtime. Test that runs for more than a few seconds\n- * should check if they should exit by calling this function regularly.\n+/**\n+ * tst_remaining_runtime() - Returns the remaining test runtime.\n *\n * The function returns remaining runtime in seconds. If runtime was used up\n * zero is returned.\n+ *\n+ * Test that runs for more than a few seconds should check if they should exit\n+ * by calling this function regularly.\n+ *\n+ * Return: the remaining test runtime in seconds.\n */\n unsigned int tst_remaining_runtime(void);\n \n-/*\n- * Sets maximal test runtime in seconds.\n+/**\n+ * tst_set_runtime() - Sets maximal test runtime in seconds.\n+ *\n+ * Allows for setting the runtime per test iteration dynamically during the test\n+ * setup phase. The runtime is specified in seconds and defines how long the\n+ * test is allowed to execute its main workload, excluding the setup and\n+ * teardown phases.\n+ *\n+ * This function is useful for tests where the duration of the main workload can\n+ * be controlled or needs to be adjusted dynamically. For example, tests that\n+ * run in a loop until the runtime expires can use this function to define how\n+ * long they should execute.\n+ *\n+ * A test that sets a runtime must monitor the remaining time with\n+ * tst_remaining_runtime() in the main loop.\n+ *\n+ * @runtime: A timeout in seconds.\n */\n void tst_set_runtime(int runtime);\n \n-/*\n- * Create and open a random file inside the given dir path.\n- * It unlinks the file after opening and return file descriptor.\n+/**\n+ * tst_creat_unlinked() - Create and open a random file inside the given\n+ * directory path, unlinks the file after opening and return file descriptor.\n+ *\n+ * @path: Path to the directory.\n+ * @flags: :manpage:`open(2)` flags.\n+ * @mode: :manpage:`open(2)` mode.\n+ *\n+ * Return: the file descriptor.\n */\n int tst_creat_unlinked(const char *path, int flags, mode_t mode);\n \n-/*\n- * Returns path to the test temporary directory root (TMPDIR).\n+/**\n+ * tst_get_tmpdir_root() - Returns path to the test temporary directory root\n+ * (TMPDIR environment variable).\n+ *\n+ * Return: the path to TMPDIR.\n */\n const char *tst_get_tmpdir_root(void);\n \n@@ -740,13 +792,16 @@ const char *tst_get_tmpdir_root(void);\n */\n bool tst_cmd_present(const char *cmd);\n \n-/*\n- * Validates exit status of child processes\n- */\n int tst_validate_children_(const char *file, const int lineno,\n \tunsigned int count);\n-#define tst_validate_children(child_count) \\\n-\ttst_validate_children_(__FILE__, __LINE__, (child_count))\n+\n+/**\n+ * tst_validate_children() - Validates exit status of the child processes.\n+ *\n+ * @count: Number of the child processes.\n+ */\n+#define tst_validate_children(count) \\\n+\ttst_validate_children_(__FILE__, __LINE__, (count))\n \n #ifndef TST_NO_DEFAULT_MAIN\n \n","prefixes":["v2","1/1"]}