1 /* 2 * Copyright (c) 2026, Arm Limited. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef FIRME_SVC_H 8 #define FIRME_SVC_H 9 10 #include <common/sha_common_macros.h> 11 #include <lib/smccc.h> 12 #include <lib/utils_def.h> 13 14 /* FIRME service versions currently supported */ 15 /* Version 0.0 returns not supported */ 16 #define FIRME_BASE_VERSION_MAJOR U(1) 17 #define FIRME_BASE_VERSION_MINOR U(0) 18 #define FIRME_GRANULE_MGMT_VERSION_MAJOR U(1) 19 #define FIRME_GRANULE_MGMT_VERSION_MINOR U(0) 20 #define FIRME_IDE_KEY_MGMT_VERSION_MAJOR U(0) 21 #define FIRME_IDE_KEY_MGMT_VERSION_MINOR U(0) 22 #define FIRME_MECID_MGMT_VERSION_MAJOR U(0) 23 #define FIRME_MECID_MGMT_VERSION_MINOR U(0) 24 #define FIRME_ATTESTATION_VERSION_MAJOR U(0) 25 #define FIRME_ATTESTATION_VERSION_MINOR U(0) 26 #define FIRME_INTEGRATED_DEVICE_MGMT_VERSION_MAJOR U(0) 27 #define FIRME_INTEGRATED_DEVICE_MGMT_VERSION_MINOR U(0) 28 29 #define FIRME_VERSION_MAJOR_SHIFT U(16) 30 #define FIRME_VERSION_MAJOR_MASK U(0x7FFF) 31 #define FIRME_VERSION_MINOR_SHIFT U(0) 32 #define FIRME_VERSION_MINOR_MASK U(0xFFFF) 33 #define FIRME_VERSION(major, minor) ((((major) & FIRME_VERSION_MAJOR_MASK) << \ 34 FIRME_VERSION_MAJOR_SHIFT) | \ 35 (((minor) & FIRME_VERSION_MINOR_MASK) << \ 36 FIRME_VERSION_MINOR_SHIFT)) 37 38 39 /* FIRME service ID definitions */ 40 typedef enum { 41 FIRME_BASE_ID = 0, 42 FIRME_GRANULE_MGMT_ID = 1, 43 FIRME_IDE_KEY_MGMT_ID = 2, 44 FIRME_MECID_MGMT_ID = 3, 45 FIRME_ATTESTATION_ID = 4, 46 FIRME_INTEGRATED_DEVICE_MGMT_ID = 5, 47 FIRME_SERVICE_ID_MAX = 6, 48 } firme_service_id_e; 49 50 typedef enum { 51 FIRME_SECURE = 0, 52 FIRME_NONSECURE = 1, 53 FIRME_REALM = 2 54 } firme_instance_e; 55 56 typedef struct { 57 uint32_t version; 58 uint8_t instance_support; 59 uint8_t num_feature_regs; 60 uint64_t feature_reg[16]; 61 } firme_service_info_t; 62 63 /* FIRME SMC return codes */ 64 #define FIRME_SUCCESS 0 65 #define FIRME_NOT_SUPPORTED -1 66 #define FIRME_INVALID_PARAMETERS -2 67 #define FIRME_ABORTED -3 68 #define FIRME_INCOMPLETE -4 69 #define FIRME_DENIED -5 70 #define FIRME_RETRY -6 71 #define FIRME_IN_PROGRESS -7 72 #define FIRME_EXISTS -8 73 #define FIRME_NO_ENTRY -9 74 #define FIRME_NO_MEMORY -10 75 #define FIRME_BAD_DATA -11 76 77 /* Range of function IDs used by FIRME interface */ 78 #define FIRME_FNUM_MIN_VALUE U(0x400) 79 #define FIRME_FNUM_MAX_VALUE U(0x412) 80 81 /* Construct FIRME fastcall std FID from offset */ 82 #define SMC64_FIRME_FID(_offset) \ 83 ((SMC_TYPE_FAST << FUNCID_TYPE_SHIFT) | (SMC_64 << FUNCID_CC_SHIFT) | \ 84 (OEN_STD_START << FUNCID_OEN_SHIFT) | \ 85 (((FIRME_FNUM_MIN_VALUE + (_offset)) & FUNCID_NUM_MASK) \ 86 << FUNCID_NUM_SHIFT)) 87 88 #define is_firme_fid(fid) \ 89 __extension__({ \ 90 __typeof__(fid) _fid = (fid); \ 91 ((GET_SMC_NUM(_fid) >= FIRME_FNUM_MIN_VALUE) && \ 92 (GET_SMC_NUM(_fid) <= FIRME_FNUM_MAX_VALUE) && \ 93 (GET_SMC_TYPE(_fid) == SMC_TYPE_FAST) && \ 94 (GET_SMC_CC(_fid) == SMC_64) && \ 95 (GET_SMC_OEN(_fid) == OEN_STD_START) && \ 96 ((_fid & 0x00FE0000) == 0U)); \ 97 }) 98 99 /* FIRME Granule Transition Bit Fields */ 100 101 #define FIRME_GM_GPI_SET_TGT_GPI_SHIFT U(0) 102 #define FIRME_GM_GPI_SET_TGT_GPI_MASK U(0xF) 103 104 /* Base service feature register definitions */ 105 #define FIRME_BASE_VERSION_BIT BIT(0) 106 #define FIRME_BASE_FEATURES_BIT BIT(1) 107 #define FIRME_BASE_MIN_SH_BUF_SZ_SHIFT U(0) 108 #define FIRME_BASE_MIN_SH_BUF_SZ_MASK U(0x3) 109 #define FIRME_BASE_MAX_SH_BUF_PG_CNT_SHIFT U(2) 110 #define FIRME_BASE_MAX_SH_BUF_PG_CNT_MASK U(0x3FFF) 111 #define FIRME_BASE_SERVICE_LIST_SHIFT U(16) 112 #define FIRME_BASE_SERVICE_LIST_MASK U(0xFFFF) 113 #define FIRME_BASE_SERVICE_GRANULE_MGMT_BIT BIT(16) 114 115 /* Granule management service feature register definitions. */ 116 #define FIRME_GM_GPI_SET_BIT BIT(0) 117 #define FIRME_GM_GPI_OP_CONTINUE_BIT BIT(1) 118 #define FIRME_GM_L1_CREATE_BIT BIT(2) 119 #define FIRME_GM_L1_DESTROY_BIT BIT(3) 120 #define FIRME_GM_PPS_SHIFT U(6) 121 #define FIRME_GM_PPS_MASK U(0x7) 122 #define FIRME_GM_L0GPTSZ_SHIFT U(2) 123 #define FIRME_GM_L0GPTSZ_MASK U(0xF) 124 #define FIRME_GM_PGS_SHIFT U(0) 125 #define FIRME_GM_PGS_MASK U(0x3) 126 127 /* 128 * FIRME_SERVICE_VERSION 129 * 130 * This function returns the supported version for a specified 131 * FIRME service. 132 * 133 * Arguments 134 * arg0(w0): Function ID 0xC4000400 135 * arg1(x1): Service ID bits[63:0] Unused 136 * bits[7:0] ID of FIRME service 137 * 138 * Return 139 * ret0(w0): Success bits[31] Set to indicate negative value 140 * bits[30:16] Major version 141 * bits[15:0] Minor version 142 * Failure Negative value encodes FIRME_NOT_SUPPORTED 143 */ 144 #define FIRME_SERVICE_VERSION_FID SMC64_FIRME_FID(U(0)) 145 146 /* 147 * FIRME_FEATURES 148 * 149 * This function returns the features supported by the FIRME interface. 150 * 151 * Supported from v1.0 152 * 153 * Arguments 154 * arg0(w0): Function ID 0xC4000401. 155 * arg1(w1): Index Index of the feature register to be returned to the 156 * caller. Current supported values are 0, 1, and 2. 157 * All others reserved. 158 * 159 * Return 160 * ret0(x0): Status FIRME_SUCCESS 161 * FIRME_NOT_SUPPORTED 162 * FIRME_INVALID_PARAMETERS 163 * ret1(x1): Requested feature register if successful. 164 */ 165 #define FIRME_SERVICE_FEATURES_FID SMC64_FIRME_FID(U(1)) 166 167 /* 168 * FIRME_GM_GPI_SET 169 * 170 * This function requests a GPI transition for a set of physically contiguous 171 * granules of memory. 172 * 173 * Supported from v1.0 174 * 175 * Arguments 176 * arg0(w0): Function ID 0xC4000402 177 * arg1(x1): Base Address Physical base address of the granules whose GPI 178 * encoding must be changed. 179 * arg2(x2): Granule Count Number of granules GPI to change starting from 180 * base address. 181 * arg3(x3): Attributes bits[63:4] Reserved 182 * bits[3:0] Target GPI encoding of the granules. 183 * 184 * Return 185 * ret0(x0): Status FIRME_SUCCESS 186 * FIRME_NOT_SUPPORTED 187 * FIRME_INVALID_PARAMETERS 188 * FIRME_DENIED 189 * FIRME_RETRY 190 * ret1(x1): Count of granules whose GPI encoding was change. 191 */ 192 #define FIRME_GM_GPI_SET_FID SMC64_FIRME_FID(U(0x2)) 193 194 /* These are unimplemented so far and will be added in the future. */ 195 196 /* Granule management service ABIs */ 197 #define FIRME_GM_GPI_OP_CONTINUE SMC64_FIRME_FID(U(0x12)) 198 #define FIRME_GM_L1_GPT_CREATE SMC64_FIRME_FID(U(0xE)) 199 #define FIRME_GM_L1_GPT_DESTROY SMC64_FIRME_FID(U(0xF)) 200 201 /* IDE key management service */ 202 #define FIRME_IDE_KEYSET_PROG SMC64_FIRME_FID(U(0x3)) 203 #define FIRME_IDE_KEYSET_GO SMC64_FIRME_FID(U(0x4)) 204 #define FIRME_IDE_KEYSET_STOP SMC64_FIRME_FID(U(0x5)) 205 #define FIRME_IDE_KEYSET_POLL SMC64_FIRME_FID(U(0x6)) 206 207 /* MECID management service */ 208 #define FIRME_MEC_REFRESH SMC64_FIRME_FID(U(0x7)) 209 210 /* Attestation service */ 211 #define FIRME_ATTEST_PAT_GET SMC64_FIRME_FID(U(0x8)) 212 #define FIRME_ATTEST_RAK_GET SMC64_FIRME_FID(U(0x9)) 213 #define FIRME_ATTEST_RAT_SIGN SMC64_FIRME_FID(U(0xA)) 214 #define FIRME_ATTEST_PAT_EXT_CLAIMS_STAGE SMC64_FIRME_FID(U(0xB)) 215 #define FIRME_ATTEST_PAT_EXT_CLAIMS_CLEAR SMC64_FIRME_FID(U(0xC)) 216 #define FIRME_ATTEST_PAT_EXT_CLAIMS_FINALISE SMC64_FIRME_FID(U(0xD)) 217 218 /* Integrated device management service */ 219 #define FIRME_IDEV_OP_START SMC64_FIRME_FID(U(0x10)) 220 #define FIRME_IDEV_OP_CONTINUE SMC64_FIRME_FID(U(0x11)) 221 222 /* Top level handler for FIRME SMC calls. */ 223 uint64_t firme_handler(uint32_t smc_fid, uint64_t x1, uint64_t x2, uint64_t x3, 224 uint64_t x4, void *cookie, void *handle, uint64_t flags); 225 226 firme_service_info_t *firme_granule_mgmt_service_get_info(void); 227 228 u_register_t firme_base_service_handler(firme_instance_e instance, uint32_t smc_fid, 229 uint64_t x1, uint64_t x2, uint64_t x3, 230 uint64_t x4, void *cookie, void *handle, 231 uint64_t flags); 232 233 u_register_t firme_granule_mgmt_service_handler(firme_instance_e instance, 234 uint32_t smc_fid, uint64_t x1, 235 uint64_t x2, uint64_t x3, 236 uint64_t x4, void *cookie, 237 void *handle, uint64_t flags); 238 239 #endif /* FIRME_SVC_H */ 240