From patchwork Thu Nov 14 10:01:10 2024 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: 13874816 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 708ADD65C69 for ; Thu, 14 Nov 2024 10:02:28 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id EB6BB10E7D5; Thu, 14 Nov 2024 10:02:27 +0000 (UTC) Authentication-Results: gabe.freedesktop.org; dkim=pass (1024-bit key; unprotected) header.d=amd.com header.i=@amd.com header.b="XS/wBEr+"; dkim-atps=neutral Received: from NAM12-DM6-obe.outbound.protection.outlook.com (mail-dm6nam12on2073.outbound.protection.outlook.com [40.107.243.73]) by gabe.freedesktop.org (Postfix) with ESMTPS id 6918910E7D5 for ; Thu, 14 Nov 2024 10:02:26 +0000 (UTC) ARC-Seal: i=1; a=rsa-sha256; s=arcselector10001; d=microsoft.com; cv=none; b=RwfsT1vzRIVJetujCmcP7Jk1aLzbY8hdRjRoMEO8RCDRkVpe2OPA4Puq5CaDcne41+SvDLXoEW6ryhmaj4UWpo4PS238Lm9Tpl+agM+1dAMuZ2tGQYkVZWCaKq86bMuauAWPGEgYCq6UKnkD3t7PMtEhIza05KQ6RQI1UVLVHLzSktdhPRxMj/IAq5xkfq7mPMA5IEeS3ifqoVpp4RTVgWzuIpKQiW34gwsJDxM05F6ILU79maLZw0kxO+151WhLR9wyevkUBNYKYiB1derxVGlBsQtDrhuMxNUGoT0NO8Ncl27y4QGXVoO0fwcHMOKd/TnvvA2NRChFBHOLm0aziA== 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=OHqlky2jJQBywqgURDkMuYDgeTAwtLcJqs5bODDYwhg=; b=fnoBsz2WEZVzuTXUcSY36u1zpnvw0ew69IZUC5NtPYgkwHiv5mNk+rr7A/ruBSL+i7lV3zrTzME65SewnFBFvDjbIoeyYcz4tUWveqnwZQuXeZ/DR3Ak9r5nyMFPfC9jtt1cY50npIW+SPbmd/FgAS4tSzYewpAVJmwSxQPpMDTLEYNBhS9tKUI/vV+DCrpPbkuLxhUj9VE8rmTSRYE1v7QA7MM0Z4LpFD8dDheEEa2LqWIpWrn4k9ovxBU3qPnpsWn4Q40snXwYRAfNCLpb7sLPUw5oVoK54RIK4Erk2m9OJs/GO1XHAyJLL4D/Zktay9ofHdEO6ZDhsjFkQk1uwA== 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=OHqlky2jJQBywqgURDkMuYDgeTAwtLcJqs5bODDYwhg=; b=XS/wBEr+m5TCAIOJmM61ov/EOqwkRD1NzfdWScIBzhJnwbpwvbxgCo6xsd8Oik9D7rse3fs+nRBzk8jciycOCOw8j/vgmKFXWzMfpIuCzaZ00ZbIxs4b9jmye9R8SgSmYXcWa/ut4vhMXSokJY22qi1/EMbFr4ex9LHPTqPT/Ig= Received: from SN7PR04CA0063.namprd04.prod.outlook.com (2603:10b6:806:121::8) by DM4PR12MB6280.namprd12.prod.outlook.com (2603:10b6:8:a2::11) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.8158.18; Thu, 14 Nov 2024 10:02:19 +0000 Received: from SA2PEPF000015C8.namprd03.prod.outlook.com (2603:10b6:806:121:cafe::f2) by SN7PR04CA0063.outlook.office365.com (2603:10b6:806:121::8) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.8158.17 via Frontend Transport; Thu, 14 Nov 2024 10:02:18 +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 SA2PEPF000015C8.mail.protection.outlook.com (10.167.241.198) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.20.8158.14 via Frontend Transport; Thu, 14 Nov 2024 10:02:18 +0000 Received: from patedamande.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; Thu, 14 Nov 2024 04:02:13 -0600 From: Pierre-Eric Pelloux-Prayer To: , , , , , , , , , , , , , , , , , , , , , , , , CC: Pierre-Eric Pelloux-Prayer Subject: [PATCH v6 7/7] drm/doc: document some tracepoints as uAPI Date: Thu, 14 Nov 2024 11:01:10 +0100 Message-ID: <20241114100113.150647-8-pierre-eric.pelloux-prayer@amd.com> X-Mailer: git-send-email 2.47.0 In-Reply-To: <20241114100113.150647-1-pierre-eric.pelloux-prayer@amd.com> References: <20241114100113.150647-1-pierre-eric.pelloux-prayer@amd.com> MIME-Version: 1.0 X-Originating-IP: [10.180.168.240] 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: SA2PEPF000015C8:EE_|DM4PR12MB6280:EE_ X-MS-Office365-Filtering-Correlation-Id: 08fdad9f-cf7b-4f9d-cc8d-08dd04936cc9 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; ARA:13230040|1800799024|7416014|376014|82310400026|36860700013|921020; X-Microsoft-Antispam-Message-Info: =?utf-8?q?leFfY1rVvllU6zKM2ljm2Aw3YOUgbHx?= =?utf-8?q?Hbx38LlXWs7A01rQRUMWsBl4pqvdCucwYBC15B66bVaXinl08xLcVN7xaaYj56Ghq?= =?utf-8?q?N9hkDSR7G8tcuNg+lk7sW7c7WIdsy7UZxsidJu7bfeBhlBXIg/VdUAGM4sYNBFjBE?= =?utf-8?q?zxdo2t/hWlHZfQnfMY+qsRWqajHCyw7tpxl36e253TRSJKZGklOV3S3kD2eqUYd2h?= =?utf-8?q?9PvGI+nhy4RnaTb9pZtGofT9DEhfb13BimnCwGn7Co4Qu0sP1v7GCHILSv6t19USv?= =?utf-8?q?V1UVLEGigCKqZhZggjML0PSIb+kEaN4C8u8MvSUD2eUwB6ZoZNyXgdG0WCTtytRAs?= =?utf-8?q?nAUY308lq/TMb22AvDgzOQ7YFHm8OnmbcaLxXgvQphDvFRL3IsInk4o8+MmTdfOOY?= =?utf-8?q?cGxo6QsVbc3dIBuLQXJCulqTsSgKWpk83/HIb6ulLkJ5jZWXP5O6nib/ia0YRY0PD?= =?utf-8?q?3uWMY/ILNHPzswznfNSJ/zWETX0xTVssEQ8/qCgGlpWGLsogvEYsDYNkTLnAINkNF?= =?utf-8?q?sb0cmK1v10pLFm14hL+n7lRxlBy9GfqC3584A5lB5H77iS3XieQpUcHkXKnnLinz0?= =?utf-8?q?ncnHn2oO0VTlWgrkp+GNUd3zbqjr/JFIsgW8iMQzaBXvghMkbDMUl9KwYFHZ5E2vg?= =?utf-8?q?v/Qxyd4dMDp2kS1ybKTH4upugL3jkYfQRuxlSjJwgKsa9gc8+HRmZCOV3ZQI0JQNj?= =?utf-8?q?yZ7UhRjKGvhzu2VIwIg5FvmAukKEnhkB6WPJmNwvlU1FD9n1tCXCkTC54a3ZY2VpU?= =?utf-8?q?qM674qq8h94LRRT/X7OMg6hbGDe8qvQdcMxvIXPVlSr4rk9uC45AeH70icJEDzoak?= =?utf-8?q?OjXiwkeyIL+smICZHxJ2fL1fBXBTB6uSSBMaNtC7xkKS9YfWOn1VhgmhsrsSe4Bbn?= =?utf-8?q?9NYzs+z0ykBJoU4lOBVq+2MqRQ6HePxj4B6EwbqvIUVrjASUoYwBPsjKJQUdKwdEX?= =?utf-8?q?hbzaooqE4TlZmZ/mBt/p0AL7xxqaZRrmEN/tj+655fhEsUn6/k7GFPHXioOZEdDd+?= =?utf-8?q?eL/croyHO35+tflM8npa8ioeokrSy0ePJ/FKR9mbtJUm//iZgt9CNEbB/5rX57CLy?= =?utf-8?q?NKc/l5XMpBg4JyZqQgA9R83ZRFORo9rfRtjihxwZEUqlSN9K2Da5U/r9jK1nwA8ZI?= =?utf-8?q?EqhYU2uiYSTOVdTIObC1NxBwqtnHl1X0OA2fKXdeurtoc/Z+kAKgCzk+P8zjjhdFZ?= =?utf-8?q?gHp+U2PW9kvowVD4ajytGfE6lEBrvp9tAJoqeL2uTn8JEhCMnySsIFuQm17Wrj4l+?= =?utf-8?q?3MdkiJ9nqd2Gj5RprxllGBA+lzqlf2C1L4fV5ctVfsPUYJqaras9ZUqc2BD4vQHr5?= =?utf-8?q?HwSFNTZkntO+X2tK+e6SkK+6YII8FslCb6Y63/0DGu65lLDIvjiqvtU=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)(1800799024)(7416014)(376014)(82310400026)(36860700013)(921020); DIR:OUT; SFP:1101; X-OriginatorOrg: amd.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 14 Nov 2024 10:02:18.7565 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 08fdad9f-cf7b-4f9d-cc8d-08dd04936cc9 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: SA2PEPF000015C8.namprd03.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: DM4PR12MB6280 X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" 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 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 b75cc9a70d1f..9603ac0f4c09 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -583,3 +583,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 8340c7c0c6b6..ec230e558961 100644 --- a/drivers/gpu/drm/scheduler/gpu_scheduler_trace.h +++ b/drivers/gpu/drm/scheduler/gpu_scheduler_trace.h @@ -33,6 +33,28 @@ #define TRACE_SYSTEM gpu_scheduler #define TRACE_INCLUDE_FILE gpu_scheduler_trace + +/** + * DOC: uAPI trace events + * + * ``drm_sched_job``, ``drm_run_job``, ``drm_sched_process_job``, + * and ``drm_sched_job_wait_dep`` are considered stable uAPI. + * + * Common trace events attributes: + * + * * ``id`` - this is &drm_sched_job->id. It uniquely idenfies a job + * inside a &struct drm_gpu_scheduler. + * + * * ``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 &dma_fence.context and the &dma_fence.seqno of + * &drm_sched_fence.finished + * + */ + #ifndef __TRACE_EVENT_GPU_SCHEDULER_PRINT_FN #define __TRACE_EVENT_GPU_SCHEDULER_PRINT_FN /* Similar to trace_print_array_seq but for fences. */