[{"id":3669550,"web_url":"http://patchwork.ozlabs.org/comment/3669550/","msgid":"","list_archive_url":null,"date":"2026-03-26T08:57:03","subject":"Re: [LTP] [PATCH 1/1] tst_test.h: Convert rest of doc to kerneldoc","submitter":{"id":8530,"url":"http://patchwork.ozlabs.org/api/people/8530/","name":"Cyril Hrubis","email":"chrubis@suse.cz"},"content":"Hi!\n> +/**\n> + * tst_set_timeout() - Sets entire timeout in seconds.\n> + *\n> + * Allows to sett the overall timeout dynamically during the test setup phase.\n ^\n\t\t set\n> + * The timeout is specified in seconds and defines the total time allowed for a\n> + * single test iteration, including the setup, runtime, and teardown phases.\n\nLooking at the code this call increases the timeout part of the overall\ntimeout. This is used only for rare cases that the test does something\nthat runs for a long time and cannot be easily interrupted (otherwise it\nwould set runtime and exit when runtime was exhausted). The description\nshould explain that instead.\n\n> + * @timeout: A timeout in seconds.\n> */\n> void tst_set_timeout(int timeout);\n> \n> +/**\n> + * tst_multiply_timeout() - Multiply the timeout with LTP_TIMEOUT_MUL\n> + * environment variable.\n\nThis is again more complex. We use the timeout multiplier but also\nlook at the kconfig.\n\nIt should be something as:\n\ntst_multiply_timeout() - Uses heuristics to multiply a time interval\nbased on expected CPU slowdowns.\n\nIf a machine is expected to be running slow for some reason a user can\nexport LTP_TIMEOUT_MUL variable that is used by this call to multiply\nthe interval. We also attempt to detect various kernel config\n(debugging) options that slown down the machine and take them into an\naccount.\n\n> + * @timeout: A timeout in seconds.\n\nTechnically the call just multiplies a number and works for any time\nunit. If you pass in minutes, you get multiplied minutes. If you pass in\nweeks, you get weeks on output...\n\n> + * Return: timeout multiplied with LTP_TIMEOUT_MUL environment variable.\n> + */\n> unsigned int tst_multiply_timeout(unsigned int timeout);\n> \n> /*\n> @@ -710,19 +724,40 @@ unsigned int tst_multiply_timeout(unsigned int timeout);\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\nMaybe add:\n\nA test that sets a runtime must monitor the remaining time with\ntst_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> @@ -738,13 +773,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> -- \n> 2.53.0\n>","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=zTZUqvji;\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=plTnM1JU;\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=zTZUqvji;\n\tdkim=neutral header.d=suse.cz header.i=@suse.cz header.a=ed25519-sha256\n header.s=susede2_ed25519 header.b=plTnM1JU;\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\tnone"],"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)\n\t(No client certificate requested)\n\tby legolas.ozlabs.org (Postfix) with ESMTPS id 4fhHhj3k1lz1y1G\n\tfor ; Thu, 26 Mar 2026 19:57:09 +1100 (AEDT)","from picard.linux.it (localhost [IPv6:::1])\n\tby picard.linux.it (Postfix) with ESMTP id 0A8703E2AC8\n\tfor ; Thu, 26 Mar 2026 09:57:07 +0100 (CET)","from in-2.smtp.seeweb.it (in-2.smtp.seeweb.it\n [IPv6:2001:4b78:1:20::2])\n (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)\n key-exchange X25519 server-signature ECDSA (secp384r1))\n (No client certificate requested)\n by picard.linux.it (Postfix) with ESMTPS id 200F83DCACD\n for ; Thu, 26 Mar 2026 09:57:04 +0100 (CET)","from smtp-out2.suse.de (smtp-out2.suse.de\n [IPv6:2a07:de40:b251:101:10:150:64:2])\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-2.smtp.seeweb.it (Postfix) with ESMTPS id 7BFC56001A2\n for ; Thu, 26 Mar 2026 09:57:03 +0100 (CET)","from imap1.dmz-prg2.suse.org (unknown [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 C9EC25BCF4;\n Thu, 26 Mar 2026 08:57:01 +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 B96D24A0A3;\n Thu, 26 Mar 2026 08:57:01 +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 MIBFLN30xGkzFwAAD6G6ig\n (envelope-from ); Thu, 26 Mar 2026 08:57:01 +0000"],"DKIM-Signature":["v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz;\n s=susede2_rsa;\n t=1774515421;\n h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc:\n mime-version:mime-version:content-type:content-type:\n in-reply-to:in-reply-to:references:references;\n bh=Nv9njegMSnFqljxMdEA3redlrRc43wt7GN14bJ1AZHs=;\n b=zTZUqvjiQdFAPswtC6OIlc+H87OMxNyFWxpiOl3Fa0KKEJS7wLuk2q8hO99f66mEu7EMBw\n nNS9CYD+f5VLiEzDCm5WjrU1i1/c6fsRf+gPalJ6GGUZTWdm/80Tktq6SBrHHPmAbdpL52\n oDhl7CHez/EtT1cDEXhyVeqWcYbw744=","v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz;\n s=susede2_ed25519; t=1774515421;\n h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc:\n mime-version:mime-version:content-type:content-type:\n in-reply-to:in-reply-to:references:references;\n bh=Nv9njegMSnFqljxMdEA3redlrRc43wt7GN14bJ1AZHs=;\n b=plTnM1JUcZM5CyZNk8YLYE1nk4No/EY1ggj76gG5DRFqSPxZNMxwdcPPbgTIWR0yZFAua7\n elv+FZKA5pXuZ1CA==","v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz;\n s=susede2_rsa;\n t=1774515421;\n h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc:\n mime-version:mime-version:content-type:content-type:\n in-reply-to:in-reply-to:references:references;\n bh=Nv9njegMSnFqljxMdEA3redlrRc43wt7GN14bJ1AZHs=;\n b=zTZUqvjiQdFAPswtC6OIlc+H87OMxNyFWxpiOl3Fa0KKEJS7wLuk2q8hO99f66mEu7EMBw\n nNS9CYD+f5VLiEzDCm5WjrU1i1/c6fsRf+gPalJ6GGUZTWdm/80Tktq6SBrHHPmAbdpL52\n oDhl7CHez/EtT1cDEXhyVeqWcYbw744=","v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz;\n s=susede2_ed25519; t=1774515421;\n h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc:\n mime-version:mime-version:content-type:content-type:\n in-reply-to:in-reply-to:references:references;\n bh=Nv9njegMSnFqljxMdEA3redlrRc43wt7GN14bJ1AZHs=;\n b=plTnM1JUcZM5CyZNk8YLYE1nk4No/EY1ggj76gG5DRFqSPxZNMxwdcPPbgTIWR0yZFAua7\n elv+FZKA5pXuZ1CA=="],"Date":"Thu, 26 Mar 2026 09:57:03 +0100","From":"Cyril Hrubis ","To":"Petr Vorel ","Message-ID":"","References":"<20260325120629.113245-1-pvorel@suse.cz>","MIME-Version":"1.0","Content-Disposition":"inline","In-Reply-To":"<20260325120629.113245-1-pvorel@suse.cz>","X-Spamd-Result":"default: False [-8.30 / 50.00]; REPLY(-4.00)[];\n BAYES_HAM(-3.00)[100.00%]; NEURAL_HAM_LONG(-1.00)[-1.000];\n NEURAL_HAM_SHORT(-0.20)[-1.000]; MIME_GOOD(-0.10)[text/plain];\n FUZZY_RATELIMITED(0.00)[rspamd.com];\n RCVD_VIA_SMTP_AUTH(0.00)[]; MIME_TRACE(0.00)[0:+];\n ARC_NA(0.00)[]; MISSING_XM_UA(0.00)[]; RCPT_COUNT_TWO(0.00)[2];\n RCVD_TLS_ALL(0.00)[];\n DKIM_SIGNED(0.00)[suse.cz:s=susede2_rsa,suse.cz:s=susede2_ed25519];\n FROM_HAS_DN(0.00)[]; TO_DN_SOME(0.00)[];\n FROM_EQ_ENVFROM(0.00)[]; RCVD_COUNT_TWO(0.00)[2];\n TO_MATCH_ENVRCPT_ALL(0.00)[];\n DBL_BLOCKED_OPENRESOLVER(0.00)[suse.cz:email]","X-Spam-Score":"-8.30","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,DMARC_MISSING,SPF_HELO_NONE,SPF_PASS\n shortcircuit=no autolearn=disabled version=4.0.1","X-Spam-Checker-Version":"SpamAssassin 4.0.1 (2024-03-25) on in-2.smtp.seeweb.it","X-Virus-Scanned":"clamav-milter 1.0.9 at in-2.smtp.seeweb.it","X-Virus-Status":"Clean","Subject":"Re: [LTP] [PATCH 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 ","Cc":"ltp@lists.linux.it","Content-Type":"text/plain; charset=\"us-ascii\"","Content-Transfer-Encoding":"7bit","Errors-To":"ltp-bounces+incoming=patchwork.ozlabs.org@lists.linux.it","Sender":"\"ltp\" "}}]