From mboxrd@z Thu Jan 1 00:00:00 1970 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 bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (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 55B2FC43458 for ; Fri, 3 Jul 2026 12:38:06 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20210309; h=Sender:List-Subscribe:List-Help :List-Post:List-Archive:List-Unsubscribe:List-Id:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-ID:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Owner; bh=s02p/1MQrFCGz0+6KO9Dxwca6u3INwyabpqBYYqGUtY=; b=eOooOiNtXhxRkt7Ys12oe/JWLF biMOOsnXS5iOpfOLO04hr3q8bU1Aq/oniJSHiUcCPamiYLzasoKeUAwjHOIDanXDbyAg5gj59PrYf Qs1GpY783ui971tv8kvQgX4LBj64NGtCTz4Yyvy35TisX2/2JNziM4DlbWB++2b9OViFPYAw3258m Swo5ZPznvQCmH7lThCXrBnCkWco27+ypRRsndu6ZWjC9cLMKSIqaxvOARtDk2o1tfnNu3KpzBaSV4 sP/CLwHYG1TcxEvIfSyUL1MkqZpKyfEPtePA2YZ7r53RG1Ag5aTxPmY6abYhd0RmcqpvqYvjPJc6V 851AMoeg==; Received: from localhost ([::1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.99.1 #2 (Red Hat Linux)) id 1wfd9a-00000006yOg-2cuW; Fri, 03 Jul 2026 12:37:58 +0000 Received: from foss.arm.com ([217.140.110.172]) by bombadil.infradead.org with esmtp (Exim 4.99.1 #2 (Red Hat Linux)) id 1wfd9W-00000006yGr-0YM4 for linux-arm-kernel@lists.infradead.org; Fri, 03 Jul 2026 12:37:57 +0000 Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 495941F60; Fri, 3 Jul 2026 05:37:49 -0700 (PDT) Received: from pluto.fritz.box (usa-sjc-mx-foss1.foss.arm.com [172.31.20.19]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id EF3E63F905; Fri, 3 Jul 2026 05:37:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=arm.com; s=foss; t=1783082273; bh=4NMjo/8gD8WONGXn/U9eRtO9felgJ9gVTdE+7fBkI5M=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FiShZkMWOQ166dehdtqttwD+X01BR+OXwXYwMcLxiJ6HDdy5e4UKzViofYzhgBM6l /wYxUm32MsYtBPS+F9yDzhz1XTt6w7v+4aQJOydyyToF73Mvt/yDsaHuwxQPm2XIxQ vz9rbq848o/6q0LH/301byZegDDhiCeKzbDObsZY= From: Cristian Marussi To: linux-kernel@vger.kernel.org, linux-arm-kernel@lists.infradead.org, arm-scmi@vger.kernel.org, linux-doc@vger.kernel.org Cc: sudeep.holla@kernel.org, james.quinlan@broadcom.com, f.fainelli@gmail.com, vincent.guittot@linaro.org, etienne.carriere@st.com, peng.fan@oss.nxp.com, michal.simek@amd.com, d-gole@ti.com, jic23@kernel.org, elif.topuz@arm.com, lukasz.luba@arm.com, philip.radford@arm.com, brauner@kernel.org, david@kernel.org, souvik.chakravarty@arm.com, leitao@kernel.org, kas@kernel.org, puranjay@kernel.org, usama.arif@linux.dev, kernel-team@meta.com, Cristian Marussi , Jonathan Corbet , Shuah Khan Subject: [PATCH v5 22/23] Documentation: Add SCMI System Telemetry documentation Date: Fri, 3 Jul 2026 13:36:00 +0100 Message-ID: <20260703123601.381275-23-cristian.marussi@arm.com> X-Mailer: git-send-email 2.54.0 In-Reply-To: <20260703123601.381275-1-cristian.marussi@arm.com> References: <20260703123601.381275-1-cristian.marussi@arm.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.9.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20260703_053754_286174_15B0D590 X-CRM114-Status: GOOD ( 19.79 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org Document ARM SCMI Telemetry IOCTLs interface. Cc: Jonathan Corbet Cc: Shuah Khan Cc: linux-doc@vger.kernel.org Signed-off-by: Cristian Marussi --- Documentation/userspace-api/index.rst | 1 + Documentation/userspace-api/stlm.rst | 143 ++++++++++++++++++++++++++ 2 files changed, 144 insertions(+) create mode 100644 Documentation/userspace-api/stlm.rst diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index a68b1bea57a8..22daa7ebf78e 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -54,6 +54,7 @@ Devices and I/O dcdbas vduse isapnp + stlm Everything else =============== diff --git a/Documentation/userspace-api/stlm.rst b/Documentation/userspace-api/stlm.rst new file mode 100644 index 000000000000..ca02281dfa2f --- /dev/null +++ b/Documentation/userspace-api/stlm.rst @@ -0,0 +1,143 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. stlm: + +======================================= +STLM - ARM SCMI Telemetry Userspace API +======================================= + +.. contents:: + +Overview +======== + +ARM SCMI is a System and Configuration Management protocol, based on a +client-server model, that defines a number of messages that allows a +client/agent like Linux to discover, configure and make use of services +provided by the server/platform firmware. + +SCMI v4.0 [1] introduced support for System Telemetry, through which an +agent can dynamically enumerate, configure and collect Telemetry Data +Events (DE) exposed by the platform. + +The SCMI System Telemetry driver expose one or more dedicated devices, +named as tlm_, grouped under /dev/scmi/, one for each discovered SCMI +instance. + +A IOCTL based interface is defined in order to enumerate, configure and +read telemetry data, as succinctly described in the following. + +For more details on the uAPI, please see include/uapi/linux/scmi.h + +Resources Enumeration +===================== + + - SCMI_TLM_GET_INFO: Gather basic Telemetry features like number of + resources and versioning information. + + - SCMI_TLM_GET_INTRVS: Enumerate available update intervals. + + - SCMI_TLM_GET_DE_INFO: Retrieve DataEvent description. + + - SCMI_TLM_GET_DE_LIST: Retrieve the list of all the existent DataEvent + dwscriptors. + + - SCMI_TLM_GET_GRP_LIST: Gather a list of descriptors for all defined Groups. + + - SCMI_TLM_GET_GRP_INFO: Gather information for a specific Group. + + - SCMI_TLM_GET_GRP_DESC: Gather detailed group composition information for + the specified Group. + + +Configuration +============= + + - SCMI_TLM_GET_CFG / SCMI_TLM_SET_CFG: Get or set the whole istance, or a + specific group, configuration. + + - SCMI_TLM_GET_DE_CFG / SCMI_TLM_SET_DE_CFG: Get or set the configuration + of a specific DataEvent. + + - SCMI_TLM_GET_ALL_CFG / SCMI_TLM_SET_ALL_CFG: Get or set the cumulative + configuration of ALL the DataEvents defined on the platform. + +Data Collection +=============== + + - SCMI_TLM_GET_DE_VALUE: Report the last udpated sample for the specified + DataEvent. + + - SCMI_TLM_BULK_READ: Report the last samples for all the currently enabled + DataEvents. + + - SCMI_TLM_BATCH_READ: Report the last samples for the DataEvents IDs + specified within the samples input params. + + - SCMI_TLM_SINGLE_SAMPLE: Trigger an immediate platform-side DataEvent + update andc report the collected samples. + +Memory Mapped Raw Access +------------------------ + + - SCMI_TLM_GET_SHMTI_LIST: Gather a list of open file descriptors, one for + each SHMTI memory areas defined for this instance, that can be used to + memory-map such areas in the calling process address space so as to be + able to directly access the SCMI Telemetry SHMTI areas shared by the + platform firmware, and parse the TDCF format. + The SCMI Telemetry TDCF format is defined in the specification at [1]. + + +Example +======= + +.. code-block:: c + + int main(int argc, char **argv) + { + struct scmi_tlm_de_config des_cfg = {}; + struct scmi_tlm_config cfg = {}; + struct scmi_tlm_de_sample samples[3] = {}; + struct scmi_tlm_data_read data = {}; + int fd, ret; + + fd = open("/dev/scmi/tlm_0", O_RDWR); + if (fd < 0) + return fd; + + /* Enable ALL Data Events with timestamps*/ + des_cfg.enable = 1; + des_cfg.t_enable = 1; + ret = ioctl(fd, SCMI_TLM_SET_ALL_CFG, &des_cfg); + if (ret) + return ret; + + /* Enable Telemetry as a whole, set a 400ms update interval */ + cfg.enable = 1; + cfg.active.secs = 400; + cfg.active.exp = -3; + + ret = ioctl(fd, SCMI_TLM_SET_CFG, &cfg); + if (ret) + return ret; + + /* Read a selection of DEs */ + samples[0].id = 0xA001; + samples[1].id = 0x0002; + samples[2].id = 0x1010; + data.num_samples = 3; + data.samples = (__u64)samples; + + ret = ioctl(fd, SCMI_TLM_BATCH_READ, &data); + if (ret) + return ret; + + for (int i = 0; i < 3; i++) + fprintf(stdout, "%llu: 0x%08X -> %llu\n", + samples[i].tstamp, samples[i].id, samples[i].val); + + return 0; + } + +References +========== +[1]: https://developer.arm.com/documentation/den0056/latest/ -- 2.54.0