1.. _arm_scmi:
2
3ARM System Control and Management Interface
4###########################################
5
6Overview
7********
8
9What is SCMI?
10*************
11
12System Control and Management Interface (SCMI) is a specification developed by
13ARM, which describes a set of OS-agnostic software interfaces used to perform
14system management (e.g: clock control, pinctrl, etc...).
15
16
17Agent, platform, protocol and transport
18***************************************
19
20The SCMI specification defines **four** key terms, which will also be used throughout
21this documentation:
22
23	#. Agent
24		Entity that performs SCMI requests (e.g: gating a clock or configuring
25		a pin). In this context, Zephyr itself is an agent.
26	#. Platform
27		This refers to a set of hardware components that handle the requests from
28		agents and provide the necessary functionality. In some cases, the requests
29		are handled by a firmware, running on a core dedicated to performing system
30		management tasks.
31	#. Protocol
32		A protocol is a set of messages grouped by functionality. Intuitively, a message
33		can be thought of as a remote procedure call.
34
35		The SCMI specification defines ten standard protocols:
36
37		#. **Base** (0x10)
38		#. **Power domain management** (0x11)
39		#. **System power management** (0x12)
40		#. **Performance domain management** (0x13)
41		#. **Clock management** (0x14)
42		#. **Sensor management** (0x15)
43		#. **Reset domain management** (0x16)
44		#. **Voltage domain management** (0x17)
45		#. **Power capping and monitoring** (0x18)
46		#. **Pin Control** (0x19)
47
48		where each of these protocols is identified by an unique protocol ID
49		(listed between brackets).
50
51		Apart from the standard protocols, the SCMI specification reserves the
52		**0x80-0xFF** protocol ID range for vendor-specific protocols.
53
54
55	#. Transport
56		This describes how messages are exchanged between agents and the platform.
57		The communication itself happens through channels.
58
59.. note::
60	A system may have more than one agent.
61
62Channels
63********
64
65A **channel** is the medium through which agents and the platform exchange messages.
66The structure of a channel and the way it works is solely dependent on the transport.
67
68Each agent has its own distinct set of channels, meaning some channel A cannot be used
69by two different agents for example.
70
71Channels are **bidirectional** (exception: FastChannels), and, depending on which entity
72initiates the communication, can be one of **two** types:
73
74	#. A2P (agent to platform)
75		The agent is the initiator/requester. The messages passed through these
76		channels are known as **commands**.
77	#. P2A (platform to agent)
78		The platform is the initiator/requester.
79
80Messages
81********
82
83The SCMI specification defines **four** types of messages:
84
85	#. Synchronous
86		These are commands that block until the platform has completed the
87		requested work and are sent over A2P channels.
88	#. Asynchronous
89		For these commands, the platform schedules the requested work to
90		be performed at a later time. As such, they return almost immediately.
91		These commands are sent over A2P channels.
92	#. Delayed response
93		These messages indicate the completion of the work associated
94		with an asynchronous command. These are sent over P2A channels.
95
96	#. Notification
97		These messages are used to notify agents of events that take place on
98		the platform. These are sent over P2A channels.
99
100The Zephyr support for SCMI is based on the documentation provided by ARM:
101`DEN0056E <https://developer.arm.com/documentation/den0056/latest/>`_. For more details
102on the specification, the readers are encouraged to have a look at it.
103
104SCMI support in Zephyr
105**********************
106
107Shared memory and doorbell-based transport
108******************************************
109
110This form of transport uses shared memory for reading/writing messages
111and doorbells for signaling. The interaction with the shared
112memory area is performed using a driver (:file:`drivers/firmware/scmi/shmem.c`),
113which offers a set of functions for this exact purpose. Furthermore,
114signaling is performed using the Zephyr MBOX API (signaling mode only, no message passing).
115
116Interacting with the shared memory area and signaling are abstracted by the
117transport API, which is implemented by the shared memory and doorbell-based
118transport driver (:file:`drivers/firmware/scmi/mailbox.c`).
119
120The steps below exemplify how the communication between the Zephyr agent
121and the platform may happen using this transport:
122
123	#. Write message to the shared memory area.
124	#. Zephyr rings request doorbell. If in ``PRE_KERNEL_1`` or ``PRE_KERNEL_2`` phase start polling for reply, otherwise wait for reply doorbell ring.
125	#. Platform reads message from shared memory area, processes it, writes the reply back to the same area and rings the reply doorbell.
126	#. Zephyr reads reply from the shared memory area.
127
128In the context of this transport, a channel is comprised of a **single** shared
129memory area and one or more mailbox channels. This is because users may need/want
130to use different mailbox channels for the request/reply doorbells.
131
132
133Protocols
134*********
135
136Currently, Zephyr has support for the following standard protocols:
137
138	#. **Power domain management**
139	#. **Clock management**
140	#. **Pin Control**
141
142NXP-specific protocols:
143	#. **CPU domain management**
144
145Power domain management
146***********************
147
148This protocol is intended for management of power states of power domains.
149This is done via a set of functions implementing various commands, for
150example, ``POWER_STATE_GET`` and ``POWER_STATE_SET``.
151
152.. note::
153	This driver is vendor-agnostic. As such, it may be used on any
154	system that uses SCMI for power domain management operations.
155
156Clock management protocol
157*************************
158
159This protocol is used to perform clock management operations. This is done
160via a driver (:file:`drivers/clock_control/clock_control_arm_scmi.c`), which
161implements the Zephyr clock control subsystem API. As such, from the user's
162perspective, using this driver is no different than using any other clock
163management driver.
164
165.. note::
166	This driver is vendor-agnostic. As such, it may be used on any
167	system that uses SCMI for clock management operations.
168
169Pin Control protocol
170********************
171
172This protocol is used to perform pin configuration operations. This is done
173via a set of functions implementing various commands. Currently, the only
174supported command is ``PINCTRL_SETTINGS_CONFIGURE``.
175
176.. note::
177	The support for this protocol **does not** include a definition for
178	the :code:`pinctrl_configure_pins` function. Each vendor should use
179	their own definition of :code:`pinctrl_configure_pins`, which should
180	call into the SCMI pin control protocol function implementing the
181	``PINCTRL_SETTINGS_CONFIGURE`` command.
182
183NXP - CPU domain management
184***************************
185
186This protocol is intended for management of cpu states.
187This is done via a set of functions implementing various commands, for
188example, ``CPU_SLEEP_MODE_SET``.
189
190.. note::
191	This driver is NXP-specific. As such, it may only be used on NXP
192	system that uses SCMI for cpu domain management operations.
193
194Enabling the SCMI support
195*************************
196
197To use the SCMI support, each vendor is required to add an ``scmi`` DT
198node (used for transport driver binding) and a ``protocol`` node under the ``scmi``
199node for each supported protocol.
200
201.. note::
202	Zephyr has no support for protocol discovery. As such, if users
203	add a DT node for a certain protocol it's assumed the platform
204	supports said protocol.
205
206The example below shows how a DT may be configured in order to use the
207SCMI support. It's assumed that the only protocol required is the clock
208management protocol.
209
210.. code-block:: devicetree
211
212	#include <mem.h>
213
214	#define MY_CLOCK_CONSUMER_CLK_ID 123
215
216	scmi_res0: memory@cafebabe {
217		/* mandatory to use shared memory driver */
218		compatible = "arm,scmi-shmem";
219		reg = <0xcafebabe DT_SIZE_K(1)>;
220	};
221
222	scmi {
223		/* compatible for shared memory and doorbell-based transport */
224		compatible = "arm,scmi";
225
226		/* one SCMI channel => A2P/transmit channel */
227		shmem = <&scmi_res0>;
228
229		/* two mailbox channels */
230		mboxes = <&my_mbox_ip 0>, <&my_mbox_ip 1>;
231		mbox-names = "tx", "tx_reply";
232
233		scmi_clk: protocol@14 {
234			compatible = "arm,scmi-clock";
235
236			/* matches the clock management protocol ID */
237			reg = <0x14>;
238
239			/* vendor-agnostic - always 1 */
240			#clock-cells = <1>;
241		};
242	};
243
244	my_mbox_ip: mailbox@deadbeef {
245		compatible = "vnd,mbox-ip";
246		reg = <0xdeadbeef DT_SIZE_K(1)>;
247		#mbox-cells = <1>;
248	};
249
250	my_clock_consumer_ip: serial@12345678 {
251		compatible = "vnd,consumer-ip";
252		reg = <0x12345678 DT_SIZE_K(1)>;
253		/* clock ID is vendor specific */
254		clocks = <&scmi_clk MY_CLOCK_CONSUMER_CLK_ID>;
255	};
256
257
258Finally, all that's left to do is enable :kconfig:option:`CONFIG_ARM_SCMI`.
259