1Arm SiP Services 2================ 3 4This document enumerates and describes the Arm SiP (Silicon Provider) services. 5 6SiP services are non-standard, platform-specific services offered by the silicon 7implementer or platform provider. They are accessed via ``SMC`` ("SMC calls") 8instruction executed from Exception Levels below EL3. SMC calls for SiP 9services: 10 11- Follow `SMC Calling Convention`_; 12- Use SMC function IDs that fall in the SiP range, which are ``0xc2000000`` - 13 ``0xc200ffff`` for 64-bit calls, and ``0x82000000`` - ``0x8200ffff`` for 32-bit 14 calls. 15 16The Arm SiP implementation offers the following services: 17 18- Performance Measurement Framework (PMF) 19- Execution State Switching service 20- DebugFS interface 21 22Source definitions for Arm SiP service are located in the ``arm_sip_svc.h`` header 23file. 24 25Performance Measurement Framework (PMF) 26--------------------------------------- 27 28The :ref:`Performance Measurement Framework <firmware_design_pmf>` 29allows callers to retrieve timestamps captured at various paths in TF-A 30execution. 31 32Execution State Switching service 33--------------------------------- 34 35Execution State Switching service provides a mechanism for a non-secure lower 36Exception Level (either EL2, or NS EL1 if EL2 isn't implemented) to request to 37switch its execution state (a.k.a. Register Width), either from AArch64 to 38AArch32, or from AArch32 to AArch64, for the calling CPU. This service is only 39available when Trusted Firmware-A (TF-A) is built for AArch64 (i.e. when build 40option ``ARCH`` is set to ``aarch64``). 41 42``ARM_SIP_SVC_EXE_STATE_SWITCH`` 43~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 44 45:: 46 47 Arguments: 48 uint32_t Function ID 49 uint32_t PC hi 50 uint32_t PC lo 51 uint32_t Cookie hi 52 uint32_t Cookie lo 53 54 Return: 55 uint32_t 56 57The function ID parameter must be ``0x82000020``. It uniquely identifies the 58Execution State Switching service being requested. 59 60The parameters *PC hi* and *PC lo* defines upper and lower words, respectively, 61of the entry point (physical address) at which execution should start, after 62Execution State has been switched. When calling from AArch64, *PC hi* must be 0. 63 64When execution starts at the supplied entry point after Execution State has been 65switched, the parameters *Cookie hi* and *Cookie lo* are passed in CPU registers 660 and 1, respectively. When calling from AArch64, *Cookie hi* must be 0. 67 68This call can only be made on the primary CPU, before any secondaries were 69brought up with ``CPU_ON`` PSCI call. Otherwise, the call will always fail. 70 71The effect of switching execution state is as if the Exception Level were 72entered for the first time, following power on. This means CPU registers that 73have a defined reset value by the Architecture will assume that value. Other 74registers should not be expected to hold their values before the call was made. 75CPU endianness, however, is preserved from the previous execution state. Note 76that this switches the execution state of the calling CPU only. This is not a 77substitute for PSCI ``SYSTEM_RESET``. 78 79The service may return the following error codes: 80 81- ``STATE_SW_E_PARAM``: If any of the parameters were deemed invalid for 82 a specific request. 83- ``STATE_SW_E_DENIED``: If the call is not successful, or when TF-A is 84 built for AArch32. 85 86If the call is successful, the caller wouldn't observe the SMC returning. 87Instead, execution starts at the supplied entry point, with the CPU registers 0 88and 1 populated with the supplied *Cookie hi* and *Cookie lo* values, 89respectively. 90 91DebugFS interface 92----------------- 93 94The optional DebugFS interface is accessed through an SMC SiP service. Refer 95to the component documentation for details. 96 97String parameters are passed through a shared buffer using a specific union: 98 99.. code:: c 100 101 union debugfs_parms { 102 struct { 103 char fname[MAX_PATH_LEN]; 104 } open; 105 106 struct mount { 107 char srv[MAX_PATH_LEN]; 108 char where[MAX_PATH_LEN]; 109 char spec[MAX_PATH_LEN]; 110 } mount; 111 112 struct { 113 char path[MAX_PATH_LEN]; 114 dir_t dir; 115 } stat; 116 117 struct { 118 char oldpath[MAX_PATH_LEN]; 119 char newpath[MAX_PATH_LEN]; 120 } bind; 121 }; 122 123Format of the dir_t structure as such: 124 125.. code:: c 126 127 typedef struct { 128 char name[NAMELEN]; 129 long length; 130 unsigned char mode; 131 unsigned char index; 132 unsigned char dev; 133 qid_t qid; 134 } dir_t; 135 136 137* Identifiers 138 139======================== ============================================= 140SMC_OK 0 141SMC_UNK -1 142DEBUGFS_E_INVALID_PARAMS -2 143======================== ============================================= 144 145======================== ============================================= 146MOUNT 0 147CREATE 1 148OPEN 2 149CLOSE 3 150READ 4 151WRITE 5 152SEEK 6 153BIND 7 154STAT 8 155INIT 10 156VERSION 11 157======================== ============================================= 158 159MOUNT 160~~~~~ 161 162Description 163^^^^^^^^^^^ 164This operation mounts a blob of data pointed to by path stored in `src`, at 165filesystem location pointed to by path stored in `where`, using driver pointed 166to by path in `spec`. 167 168Parameters 169^^^^^^^^^^ 170======== ============================================================ 171uint32_t FunctionID (0x82000030 / 0xC2000030) 172uint32_t ``MOUNT`` 173======== ============================================================ 174 175Return values 176^^^^^^^^^^^^^ 177 178=============== ========================================================== 179int32_t w0 == SMC_OK on success 180 181 w0 == DEBUGFS_E_INVALID_PARAMS if mount operation failed 182=============== ========================================================== 183 184OPEN 185~~~~ 186 187Description 188^^^^^^^^^^^ 189This operation opens the file path pointed to by `fname`. 190 191Parameters 192^^^^^^^^^^ 193 194======== ============================================================ 195uint32_t FunctionID (0x82000030 / 0xC2000030) 196uint32_t ``OPEN`` 197uint32_t mode 198======== ============================================================ 199 200mode can be one of: 201 202.. code:: c 203 204 enum mode { 205 O_READ = 1 << 0, 206 O_WRITE = 1 << 1, 207 O_RDWR = 1 << 2, 208 O_BIND = 1 << 3, 209 O_DIR = 1 << 4, 210 O_STAT = 1 << 5 211 }; 212 213Return values 214^^^^^^^^^^^^^ 215 216=============== ========================================================== 217int32_t w0 == SMC_OK on success 218 219 w0 == DEBUGFS_E_INVALID_PARAMS if open operation failed 220 221uint32_t w1: file descriptor id on success. 222=============== ========================================================== 223 224CLOSE 225~~~~~ 226 227Description 228^^^^^^^^^^^ 229 230This operation closes a file described by a file descriptor obtained by a 231previous call to OPEN. 232 233Parameters 234^^^^^^^^^^ 235 236======== ============================================================ 237uint32_t FunctionID (0x82000030 / 0xC2000030) 238uint32_t ``CLOSE`` 239uint32_t File descriptor id returned by OPEN 240======== ============================================================ 241 242Return values 243^^^^^^^^^^^^^ 244=============== ========================================================== 245int32_t w0 == SMC_OK on success 246 247 w0 == DEBUGFS_E_INVALID_PARAMS if close operation failed 248=============== ========================================================== 249 250READ 251~~~~ 252 253Description 254^^^^^^^^^^^ 255 256This operation reads a number of bytes from a file descriptor obtained by 257a previous call to OPEN. 258 259Parameters 260^^^^^^^^^^ 261 262======== ============================================================ 263uint32_t FunctionID (0x82000030 / 0xC2000030) 264uint32_t ``READ`` 265uint32_t File descriptor id returned by OPEN 266uint32_t Number of bytes to read 267======== ============================================================ 268 269Return values 270^^^^^^^^^^^^^ 271 272On success, the read data is retrieved from the shared buffer after the 273operation. 274 275=============== ========================================================== 276int32_t w0 == SMC_OK on success 277 278 w0 == DEBUGFS_E_INVALID_PARAMS if read operation failed 279 280uint32_t w1: number of bytes read on success. 281=============== ========================================================== 282 283SEEK 284~~~~ 285 286Description 287^^^^^^^^^^^ 288 289Move file pointer for file described by given `file descriptor` of given 290`offset` related to `whence`. 291 292Parameters 293^^^^^^^^^^ 294 295======== ============================================================ 296uint32_t FunctionID (0x82000030 / 0xC2000030) 297uint32_t ``SEEK`` 298uint32_t File descriptor id returned by OPEN 299sint32_t offset in the file relative to whence 300uint32_t whence 301======== ============================================================ 302 303whence can be one of: 304 305========= ============================================================ 306KSEEK_SET 0 307KSEEK_CUR 1 308KSEEK_END 2 309========= ============================================================ 310 311Return values 312^^^^^^^^^^^^^ 313 314=============== ========================================================== 315int32_t w0 == SMC_OK on success 316 317 w0 == DEBUGFS_E_INVALID_PARAMS if seek operation failed 318=============== ========================================================== 319 320BIND 321~~~~ 322 323Description 324^^^^^^^^^^^ 325 326Create a link from `oldpath` to `newpath`. 327 328Parameters 329^^^^^^^^^^ 330 331======== ============================================================ 332uint32_t FunctionID (0x82000030 / 0xC2000030) 333uint32_t ``BIND`` 334======== ============================================================ 335 336Return values 337^^^^^^^^^^^^^ 338 339=============== ========================================================== 340int32_t w0 == SMC_OK on success 341 342 w0 == DEBUGFS_E_INVALID_PARAMS if bind operation failed 343=============== ========================================================== 344 345STAT 346~~~~ 347 348Description 349^^^^^^^^^^^ 350 351Perform a stat operation on provided file `name` and returns the directory 352entry statistics into `dir`. 353 354Parameters 355^^^^^^^^^^ 356 357======== ============================================================ 358uint32_t FunctionID (0x82000030 / 0xC2000030) 359uint32_t ``STAT`` 360======== ============================================================ 361 362Return values 363^^^^^^^^^^^^^ 364 365=============== ========================================================== 366int32_t w0 == SMC_OK on success 367 368 w0 == DEBUGFS_E_INVALID_PARAMS if stat operation failed 369=============== ========================================================== 370 371INIT 372~~~~ 373 374Description 375^^^^^^^^^^^ 376Initial call to setup the shared exchange buffer. Notice if successful once, 377subsequent calls fail after a first initialization. The caller maps the same 378page frame in its virtual space and uses this buffer to exchange string 379parameters with filesystem primitives. 380 381Parameters 382^^^^^^^^^^ 383 384======== ============================================================ 385uint32_t FunctionID (0x82000030 / 0xC2000030) 386uint32_t ``INIT`` 387uint64_t Physical address of the shared buffer. 388======== ============================================================ 389 390Return values 391^^^^^^^^^^^^^ 392 393=============== ====================================================== 394int32_t w0 == SMC_OK on success 395 396 w0 == DEBUGFS_E_INVALID_PARAMS if already initialized, 397 or internal error occurred. 398=============== ====================================================== 399 400VERSION 401~~~~~~~ 402 403Description 404^^^^^^^^^^^ 405Returns the debugfs interface version if implemented in TF-A. 406 407Parameters 408^^^^^^^^^^ 409 410======== ============================================================ 411uint32_t FunctionID (0x82000030 / 0xC2000030) 412uint32_t ``VERSION`` 413======== ============================================================ 414 415Return values 416^^^^^^^^^^^^^ 417 418=============== ====================================================== 419int32_t w0 == SMC_OK on success 420 421 w0 == SMC_UNK if interface is not implemented 422 423uint32_t w1: On success, debugfs interface version, 32 bits 424 value with major version number in upper 16 bits and 425 minor version in lower 16 bits. 426=============== ====================================================== 427 428* CREATE(1) and WRITE (5) command identifiers are unimplemented and 429 return `SMC_UNK`. 430 431-------------- 432 433*Copyright (c) 2017-2020, Arm Limited and Contributors. All rights reserved.* 434 435.. _SMC Calling Convention: https://developer.arm.com/docs/den0028/latest 436