From patchwork Wed May 21 15:45:11 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Pierre-Eric Pelloux-Prayer X-Patchwork-Id: 891613 Received: from NAM11-CO1-obe.outbound.protection.outlook.com (mail-co1nam11on2082.outbound.protection.outlook.com [40.107.220.82]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 1DEA9220F57; Wed, 21 May 2025 15:47:51 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=fail smtp.client-ip=40.107.220.82 ARC-Seal: i=2; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1747842474; cv=fail; b=nzDF0eEVYsW4AkCKmPbAQ3XKUmldwmrvRR2AEulHo7henh/HQyIKheH4DabQQwtmwZfvt0f0cWrg/PUjDlAwADrGYZvHBNgByRDIPQ5JuX/ZRwQZ1MmzXEpFUGJX3JR0UpTA+EvPPZmF6T42f/PzK07nT8J2/QMljcK5r3qDFR0= ARC-Message-Signature: i=2; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1747842474; c=relaxed/simple; bh=jhpGfvv6CWUzPoQCHO3Atk0OtyqOuJlyW3j0S+K3L1o=; h=From:To:CC:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=EH1QgOsZzRUUOYjYEM4HG2N5g9d734yfggyBlLkVvyQP2+/gTOP7WdtzoY0Rpm90bbKtb62q7jT7lYl5vNi6BnNvgXUgE3AcTibD4wjUsuEjQbkbWdOVMEQncP2V67ahkafOvG3sq3cgUC/rVwbex3h6glDrYSEfZ24HAf0b9gM= ARC-Authentication-Results: i=2; smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=amd.com; spf=fail smtp.mailfrom=amd.com; dkim=pass (1024-bit key) header.d=amd.com header.i=@amd.com header.b=0vemNurX; arc=fail smtp.client-ip=40.107.220.82 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=amd.com Authentication-Results: smtp.subspace.kernel.org; spf=fail smtp.mailfrom=amd.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=amd.com header.i=@amd.com header.b="0vemNurX" ARC-Seal: i=1; a=rsa-sha256; s=arcselector10001; d=microsoft.com; cv=none; b=DrOxjw0Hg4gPt5nab6D73dB9MLsysGIGQxG9ebylqzsbiK9n6V1osdY8ieVvQyggsYPdV0K1hVB8ySfTuqxJJ+XWNhZYPk/EeEeOEt2jUzdYK662Lh0J3xC3DKPkXpkCzxkBm0JIgWrQkp11qEx6pt8YutqEzn/iAgmLZT8emnU3KhImNRIVzM5RnWq90QfcGojRx0hbdh2OWNfokKt2fvYQfjDG0ZOU6+BJT+lyNvk3FuNIew+Dn8QwTUnvAjibZqjnrlgJ7xH6UMQpTj5d2uOM2zOMI5eWTs/W+mp9qcV+fnxEz8IoU1/Fc2XBPc3TBlvt6C8B/mUMZ/3nHWrRqg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector10001; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=zw2huqsza4q5J5wpoyqjqOyZRA3CmN84hy7iWKy+kRo=; b=nqbKFO059KkRT14+F8izeNXRFsyaXq6vEOe1pvVvc1faA/rm/At94CRAvoaCPqEH7ICPgUog6V3NG2GOjK+odBJFoSQH7CF6FKyNfUeQ6qciTsSgsG+d6CgtKxK4ymd3FBJuuQHl3R2JM5AAZfzJ1655DCA+GUMSDte00xM9x8dWvl21npmvL/zTdf/zrLXO2az0di7qYrRyJqxwnlDhuQ8jRuW4rLz7/cLyeohuzqw8ZoVqNAZw+bmtpG7wGhFWtUTs6IlfwzT1tzDRoAqNHO3WCs4fSVhS0IkZYSdZByVuX6qj7LN8DtJ0YPPx4bJeJ1KjShXMuoR7j9iNXJvCTA== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass (sender ip is 165.204.84.17) smtp.rcpttodomain=gmail.com smtp.mailfrom=amd.com; dmarc=pass (p=quarantine sp=quarantine pct=100) action=none header.from=amd.com; dkim=none (message not signed); arc=none (0) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=amd.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=zw2huqsza4q5J5wpoyqjqOyZRA3CmN84hy7iWKy+kRo=; b=0vemNurXepMuTJfrnSSQg4YZiYryBPqDASCZu/Kz3PquREWSgI3ZN7auo3d0/t+7vS3IaKQEnkh8xyhlBj/iD/9YW6shLlr00dBIzUwUnWRI7elDKOCarZQGECKI7gJQt8+q2l8+s7OS2WAj26p12rj0RIXk34Rt3uvQ6+RbSKA= Received: from DS7PR03CA0268.namprd03.prod.outlook.com (2603:10b6:5:3b3::33) by CYYPR12MB8921.namprd12.prod.outlook.com (2603:10b6:930:c7::14) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.8746.30; Wed, 21 May 2025 15:47:49 +0000 Received: from DS1PEPF00017092.namprd03.prod.outlook.com (2603:10b6:5:3b3:cafe::18) by DS7PR03CA0268.outlook.office365.com (2603:10b6:5:3b3::33) with Microsoft SMTP Server (version=TLS1_3, cipher=TLS_AES_256_GCM_SHA384) id 15.20.8769.18 via Frontend Transport; Wed, 21 May 2025 15:47:49 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 165.204.84.17) smtp.mailfrom=amd.com; dkim=none (message not signed) header.d=none;dmarc=pass action=none header.from=amd.com; Received-SPF: Pass (protection.outlook.com: domain of amd.com designates 165.204.84.17 as permitted sender) receiver=protection.outlook.com; client-ip=165.204.84.17; helo=SATLEXMB04.amd.com; pr=C Received: from SATLEXMB04.amd.com (165.204.84.17) by DS1PEPF00017092.mail.protection.outlook.com (10.167.17.135) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.20.8769.18 via Frontend Transport; Wed, 21 May 2025 15:47:49 +0000 Received: from FRAPPELLOUX01.amd.com (10.180.168.240) by SATLEXMB04.amd.com (10.181.40.145) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.39; Wed, 21 May 2025 10:47:46 -0500 From: Pierre-Eric Pelloux-Prayer To: David Airlie , Simona Vetter , "Maarten Lankhorst" , Maxime Ripard , Thomas Zimmermann , "Jonathan Corbet" , Matthew Brost , "Danilo Krummrich" , Philipp Stanner , =?utf-8?q?Christian_K=C3=B6nig?= , "Sumit Semwal" CC: Pierre-Eric Pelloux-Prayer , "Lucas Stach" , =?utf-8?q?Ma=C3=ADra_Canal?= , =?utf-8?q?Christian_K?= =?utf-8?q?=C3=B6nig?= , , , , , Subject: [PATCH v10 09/10] drm/doc: Document some tracepoints as uAPI Date: Wed, 21 May 2025 17:45:11 +0200 Message-ID: <20250521154531.10541-10-pierre-eric.pelloux-prayer@amd.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20250521154531.10541-1-pierre-eric.pelloux-prayer@amd.com> References: <20250521154531.10541-1-pierre-eric.pelloux-prayer@amd.com> Precedence: bulk X-Mailing-List: linux-media@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-ClientProxiedBy: SATLEXMB03.amd.com (10.181.40.144) To SATLEXMB04.amd.com (10.181.40.145) X-EOPAttributedMessage: 0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: DS1PEPF00017092:EE_|CYYPR12MB8921:EE_ X-MS-Office365-Filtering-Correlation-Id: b0d82ef2-6a9e-4d56-b781-08dd987ed724 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; ARA:13230040|36860700013|1800799024|82310400026|376014|7416014|921020; X-Microsoft-Antispam-Message-Info: =?utf-8?q?0PjqyJUs9hYrALdHqM5JrKvgjmyL+WL?= =?utf-8?q?UeOYF6GV1QhuGVdVjtKtAUO+ADPZknzEyINpEwm+0FnvO9l5vd7tnISHevxjo0GNR?= =?utf-8?q?KznUzFxSGjieMzxPiougXxUgZr4h/x6CZ1wKYLRPMKexOYirdsQ8A/1CXGnyFh7sH?= =?utf-8?q?tT5QYDa81CDdZPT8H1kbg3pJ0Ao0Kpp4ZYvtWTHhfSLs8kucIqSEvUd7j5q1KRND1?= =?utf-8?q?TYwjSS1YwoUkFCYT8Cf9hlCYdJsuq/vTQUlILTsqa3L0V2GMLcqy1yzB9o6hyAqIg?= =?utf-8?q?+vFDvEap+WjyjNWtjMNPxXTdB44Obu8V79fmGoGL/V7lR+lbRQN6QNPXvak43WLWZ?= =?utf-8?q?sbigsHzEOinYmx/Nm5OoZAekAsCLkyH6W2npN2VQxsL3y7s6VfxDUUsQAe3ILcsDN?= =?utf-8?q?Sfn2V07SuvYwm2ZGKPqpKVAgRjpRJ9JTnGbXpOGQ1ULc85efoziKPPBoQcgpJVSSW?= =?utf-8?q?aUuBN4Z8EnQsq+Tieo/k6d7HztMFrwU8oFQfAuq73RG/x2qvuzLU2UOf1gyrIlm8c?= =?utf-8?q?jtX1N5mW8h7bUxqhwGLb7H8PDCrla3Gs6uU9IOwPmwIfX3ZvJCzU2YdPYeaGIUfsw?= =?utf-8?q?uub2iAT+K/2n6mb9uAxu9EV5zEETK+P1mFnU2jtucUBfdVG3tPALM14WxnWc6l8js?= =?utf-8?q?mawyUhihet9xlAnt1uOaFJ9BakIfm7+JdYGHv8DQpIyFGUAwYGRxn07VtN3CjeZe2?= =?utf-8?q?mBz6wRmrBwnRi/EFKXWp59RXbn7d/BsIUtij3IczDKS9SpfRQUqNGwrLawQu1SfyH?= =?utf-8?q?8r8Ybp/jsCZni+fdM2bfxUz+OTUWuUnfePas/0LsbXnIThcJILMt319He709kHtw3?= =?utf-8?q?TJFsyQCD4r+2sN9j62XkTT0zz5hvL7qGjX/NSIC7Upi9OFnp+erm71zSUgG5cCFvp?= =?utf-8?q?LVnUr1Q+OfMUJ3Oj9U9abfREtk+5FuMW/IsMaBSYUQ1IwAVvXP0x54YiBwQPyzkfr?= =?utf-8?q?oWqYTowwuX5X9Rgj1QpMlQqLcwpWsRQlziax8XJt+63GcD9wJtTvj7FkhqkVSs6og?= =?utf-8?q?E074WAXYHk5KSJwE5ggf8yrRdDqXVU9FbaJUVogzXGqs8oJbcqi44gMZqddoOyYrx?= =?utf-8?q?c2BIK4J6taespXAkNw/SerKjzcGvdc0JIO1fgbWkYDTti3K1M6HRmvlXN5m+7BMpP?= =?utf-8?q?HRZFdF+bI3DLlkYAekvLmIosngK8mWJnoRTPOvN8sJZ0FRC5lJ7xiZ/rk8xzaSykT?= =?utf-8?q?lQzUvSjIZJpIaCf2Hl4+4EbKw2zmpEmcZLYERRFLQt+Tw3ZAKbg+iZ/bPZaw7foxn?= =?utf-8?q?cnDzj35/r7Q2VHj8hGetDSHS8/wzZf1OMo6bGSW+pdGbJcQSEr05homAEya16RDfq?= =?utf-8?q?GoKPO8am0SRi9XF8tuIkJ25Dwhjxi26A6GLEE9uAEK/V0jHAj4NXmmOE7bjHu9YdV?= =?utf-8?q?DQ5iWGVR1+7Hg4LRM40N/CJOxDzmRBDJfCW8zLhouoGrmhP+nUYiyvo5LVNC2Aoja?= =?utf-8?q?vMQi6MH4RqOzZuaWhPGRXdz3CP6pDP1w=3D=3D?= X-Forefront-Antispam-Report: CIP:165.204.84.17; CTRY:US; LANG:en; SCL:1; SRV:; IPV:CAL; SFV:NSPM; H:SATLEXMB04.amd.com; PTR:InfoDomainNonexistent; CAT:NONE; SFS:(13230040)(36860700013)(1800799024)(82310400026)(376014)(7416014)(921020); DIR:OUT; SFP:1101; X-OriginatorOrg: amd.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 21 May 2025 15:47:49.8476 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: b0d82ef2-6a9e-4d56-b781-08dd987ed724 X-MS-Exchange-CrossTenant-Id: 3dd8961f-e488-4e60-8e11-a82d994e183d X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=3dd8961f-e488-4e60-8e11-a82d994e183d; Ip=[165.204.84.17]; Helo=[SATLEXMB04.amd.com] X-MS-Exchange-CrossTenant-AuthSource: DS1PEPF00017092.namprd03.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: CYYPR12MB8921 This commit adds a document section in drm-uapi.rst about tracepoints, and mark the events gpu_scheduler_trace.h as stable uAPI. The goal is to explicitly state that tools can rely on the fields, formats and semantics of these events. Acked-by: Lucas Stach Acked-by: Maíra Canal Reviewed-by: Christian König Signed-off-by: Pierre-Eric Pelloux-Prayer --- Documentation/gpu/drm-uapi.rst | 19 ++++++++++++++++ .../gpu/drm/scheduler/gpu_scheduler_trace.h | 22 +++++++++++++++++++ 2 files changed, 41 insertions(+) diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 69f72e71a96e..4863a4deb0ee 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -693,3 +693,22 @@ dma-buf interoperability Please see Documentation/userspace-api/dma-buf-alloc-exchange.rst for information on how dma-buf is integrated and exposed within DRM. + + +Trace events +============ + +See Documentation/trace/tracepoints.rst for information about using +Linux Kernel Tracepoints. +In the DRM subsystem, some events are considered stable uAPI to avoid +breaking tools (e.g.: GPUVis, umr) relying on them. Stable means that fields +cannot be removed, nor their formatting updated. Adding new fields is +possible, under the normal uAPI requirements. + +Stable uAPI events +------------------ + +From ``drivers/gpu/drm/scheduler/gpu_scheduler_trace.h`` + +.. kernel-doc:: drivers/gpu/drm/scheduler/gpu_scheduler_trace.h + :doc: uAPI trace events \ No newline at end of file diff --git a/drivers/gpu/drm/scheduler/gpu_scheduler_trace.h b/drivers/gpu/drm/scheduler/gpu_scheduler_trace.h index 781b20349389..261713dd7d5a 100644 --- a/drivers/gpu/drm/scheduler/gpu_scheduler_trace.h +++ b/drivers/gpu/drm/scheduler/gpu_scheduler_trace.h @@ -32,6 +32,28 @@ #define TRACE_SYSTEM gpu_scheduler #define TRACE_INCLUDE_FILE gpu_scheduler_trace +/** + * DOC: uAPI trace events + * + * ``drm_sched_job_queue``, ``drm_sched_job_run``, ``drm_sched_job_add_dep``, + * ``drm_sched_job_done`` and ``drm_sched_job_unschedulable`` are considered + * stable uAPI. + * + * Common trace events attributes: + * + * * ``dev`` - the dev_name() of the device running the job. + * + * * ``ring`` - the hardware ring running the job. Together with ``dev`` it + * uniquely identifies where the job is going to be executed. + * + * * ``fence`` - the &struct dma_fence.context and the &struct dma_fence.seqno of + * &struct drm_sched_fence.finished + * + * All the events depends on drm_sched_job_arm() having been called already for + * the job because they use &struct drm_sched_job.sched or + * &struct drm_sched_job.s_fence. + */ + DECLARE_EVENT_CLASS(drm_sched_job, TP_PROTO(struct drm_sched_job *sched_job, struct drm_sched_entity *entity), TP_ARGS(sched_job, entity),