From patchwork Wed Jul 12 14:28:53 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11935 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:a6b2:0:b0:3e4:2afc:c1 with SMTP id c18csp1200025vqm; Wed, 12 Jul 2023 07:44:57 -0700 (PDT) X-Google-Smtp-Source: APBJJlFwPTTEJkhi7mU4QZnenJKiy4pHLaiaa8wJcwJOwuEl02tq/OH/HaRD7XjdxJRYnqnBHCo/ X-Received: by 2002:a05:6a20:12c8:b0:12c:a8e9:7bf6 with SMTP id v8-20020a056a2012c800b0012ca8e97bf6mr3160769pzg.10.1689173097246; Wed, 12 Jul 2023 07:44:57 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1689173097; cv=none; d=google.com; s=arc-20160816; b=rI2oESh2iTgBeqI/1sEgVAFoMqQLcTvzNGT0Xncpamd7+YKAK1GtGMpZoyQNOXyCtf A+tvFSL0PXvFZdHj//Kj5N+B2/2OMCFMGLuQezZZC26xuTFpGYVpTee4z8PuCOxdwsuM j/TO+8gF0QgyQmZUMUuL6+67tjUliNYXd80vFrE2B0ykPTUeBpH/YZQW5mS2+RiKHAxB aAY8QGnxWBqKYRV5R9MruLgQnKWvUcxc0o9M1YmP2dARV5RZzWA4RVVwkwJL/XFLZf5G 83VCEy3P3scPL4IPeviGvWGSnwgn2Z0QmIjwH1AdU9+Q4WVW4dcxxT2yQEzEAjBtHc6V hlpA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:to:content-transfer-encoding:mime-version :message-id:date:subject:cc:from:dkim-signature; bh=nCZrflyHaUloe4dT5fpZdNx6ZDQhs04XGmR1H8tIHuU=; fh=Tj9n/WDGLxJaN0J5NcuIx4rkHH6k9Rh6fMzuZYyllmA=; b=FUT9Q/wQa3qdGxfX0Isq5sPzEq//Whtff58Gb1dgUMpRaTW01gVcnT+SQfEWPaBOZ9 dtQ3Qiz0dkRI/raJ2Wfvnw7+tLc1ic7tMEfgBJfSpNAxhF4j6zEJx4a1BFnPiz39hoO4 MURWx7JbSD198ju0wmkO02dYlx9inAubHrtBoikelAdqpqNTz57TixbKkcvcafIt7QRG qMRZ201vWgr8Er3kT2w+yeJTYRCvftoWIJ6kVQM4D7Rhdh0GQpCG2bdidcIEly53zBXQ 5pWMYzL2ZyNfzgK7gbCS57P5DlMtbPRsU7mQuGq0m20+8Cy61IdFsxJl9Pg79zsMJx+/ YbYQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@kernel.org header.s=k20201202 header.b=uRpRe2FB; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id g12-20020a056a000b8c00b0067bf9a05b45si3465123pfj.110.2023.07.12.07.44.43; Wed, 12 Jul 2023 07:44:57 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=fail header.i=@kernel.org header.s=k20201202 header.b=uRpRe2FB; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230086AbjGLO3K (ORCPT + 99 others); Wed, 12 Jul 2023 10:29:10 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:33284 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232375AbjGLO3D (ORCPT ); Wed, 12 Jul 2023 10:29:03 -0400 Received: from dfw.source.kernel.org (dfw.source.kernel.org [139.178.84.217]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D78111BE2; Wed, 12 Jul 2023 07:29:01 -0700 (PDT) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by dfw.source.kernel.org (Postfix) with ESMTPS id 69F776181D; Wed, 12 Jul 2023 14:29:01 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id C7056C433CA; Wed, 12 Jul 2023 14:29:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1689172140; bh=HQ7aGbV4C7uaZAHLezNUkQSJsAkwtDjgQS3l2fLDv8g=; h=From:To:Cc:Subject:Date:From; b=uRpRe2FBwR2ytkiG/aO3Bgltf6Rdz5u2Hx/03RuV00p8Npi4EuH/K0928b5lJ9oF2 RmzOqo+2LMt6zjoDLTjyEwk3SHpJSSq/K4PwkpYk8GRpw2p6oBBeaya0FEt0YM7OXu OKltFvcyQrcfuXzCbVYENGQQvcDJvO8idxR92BNmXt50jz/lHK34Tu2IKAbfo31pG7 h5itJpBHiK+TzHHO2zuHsylG65j9wV7cpHkqW7IeFs58fSIuH6nKcuhMew8FdnSWax jUbccFbSCDs6uTd8yLMxYeN+UFu4JFntosz8h7ij9pKeF7lLgDQoQkgQ+FUL2IDcYU QHQH2PQWCwQsA== Received: from mchehab by mail.kernel.org with local (Exim 4.96) (envelope-from ) id 1qJapt-003bek-1S; Wed, 12 Jul 2023 16:28:57 +0200 From: Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , David Gow , Shuah Khan , Jonathan Corbet , Nikolai Kondrashov , linux-kselftest@vger.kernel.org, kunit-dev@googlegroups.com, mauro.chehab@intel.com, linux-doc@vger.kernel.org, Brendan Higgins , Rae Moar , dri-devel@lists.freedesktop.org, linux-kernel@vger.kernel.org Subject: [PATCH RFC 0/2] Add support for inlined documentation for kunit and kselftests Date: Wed, 12 Jul 2023 16:28:53 +0200 Message-Id: X-Mailer: git-send-email 2.40.1 MIME-Version: 1.0 X-Spam-Status: No, score=-7.1 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_HI, SPF_HELO_NONE,SPF_PASS,T_SCC_BODY_TEXT_LINE,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net To: unlisted-recipients:; (no To-header on input) Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1771226369685393391 X-GMAIL-MSGID: 1771226369685393391 This RFC is a follow-up of the discussions taken here: https://lore.kernel.org/linux-doc/20230704132812.02ba97ba@maurocar-mobl2/T/#t It adds a new extension that allows documenting tests using the same tool we're using for DRM unit tests at IGT GPU tools: https://gitlab.freedesktop.org/drm/igt-gpu-tools. While kernel-doc has provided documentation for in-lined functions/struct comments, it was not meant to document tests. Tests need to be grouped by the test functions. It should also be possible to produce other outputs from the documentation, to integrate it with test suites. For instance, Internally at Intel, we use the comments to generate DOT files hierarchically grouped per feature categories. This is just an initial RFC to start discussions around the solution. Before being merged upstream, we need to define what tags will be used to identify test markups and add a simple change at kernel-doc to let it ignore such markups. On this series, we have: - patch 1: adding test_list.py as present at the IGT tree, after a patch series to make it more generic: https://patchwork.freedesktop.org/series/120622/ - patch 2: adds an example about how tests could be documented. This is a really simple example, just to test the feature, specially designed to make easy to build just the test documentation from a single DRM kunit file. After discussions, my plan is to send a new version addressing the issues, and add some documentation for DRM and/or i915 kunit tests. Mauro Carvalho Chehab (2): docs: add support for documenting kUnit and kSelftests drm: add documentation for drm_buddy_test kUnit test Documentation/conf.py | 2 +- Documentation/index.rst | 2 +- Documentation/sphinx/test_kdoc.py | 108 ++ Documentation/sphinx/test_list.py | 1288 ++++++++++++++++++++++++ Documentation/tests/index.rst | 6 + Documentation/tests/kunit.rst | 5 + drivers/gpu/drm/tests/drm_buddy_test.c | 12 + 7 files changed, 1421 insertions(+), 2 deletions(-) create mode 100644 Documentation/sphinx/test_kdoc.py create mode 100644 Documentation/sphinx/test_list.py create mode 100644 Documentation/tests/index.rst create mode 100644 Documentation/tests/kunit.rst