1 /** @addtogroup MCP 2 * @{ 3 * The MCP defines commands and responses which are used to control the MobiCore system. 4 * MCP information is exchanged in a world share memory buffer which has been established prior between NWd 5 * and SWd using the FastCall interface. The buffer needs to be provided by the MobiCore driver and is utilized 6 * to send MCP commands to the MobiCore as well as receiving responses from the MobiCore. 7 * The command of the normal world will be overwritten with the response from the secure side. 8 * 9 * @file 10 * MCP command interface definitions. 11 * 12 * <!-- Copyright Giesecke & Devrient GmbH 2009-2012 --> 13 * 14 * Redistribution and use in source and binary forms, with or without 15 * modification, are permitted provided that the following conditions 16 * are met: 17 * 1. Redistributions of source code must retain the above copyright 18 * notice, this list of conditions and the following disclaimer. 19 * 2. Redistributions in binary form must reproduce the above copyright 20 * notice, this list of conditions and the following disclaimer in the 21 * documentation and/or other materials provided with the distribution. 22 * 3. The name of the author may not be used to endorse or promote 23 * products derived from this software without specific prior 24 * written permission. 25 * 26 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS 27 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 28 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 29 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY 30 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 32 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 33 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 34 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 35 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 36 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 37 */ 38 #ifndef MCP_H_ 39 #define MCP_H_ 40 41 #include "mcUuid.h" 42 #include "mcLoadFormat.h" 43 #include "mcVersionInfo.h" 44 45 /** MobiCore Return Code Defines. 46 * List of the possible MobiCore return codes. 47 */ 48 typedef enum { 49 MC_MCP_RET_OK = 0, /**< Memory has successfully been mapped. */ 50 MC_MCP_RET_ERR_INVALID_SESSION = 1, /**< The session ID is invalid. */ 51 MC_MCP_RET_ERR_UNKNOWN_UUID = 2, /**< The UUID of the Trustlet is unknown. */ 52 MC_MCP_RET_ERR_UNKNOWN_DRIVER_ID = 3, /**< The ID of the driver is unknown. */ 53 MC_MCP_RET_ERR_NO_MORE_SESSIONS = 4, /**< No more session are allowed. */ 54 MC_MCP_RET_ERR_CONTAINER_INVALID = 5, /**< The container is invalid. */ 55 MC_MCP_RET_ERR_TRUSTLET_INVALID = 6, /**< The Trustlet is invalid. */ 56 MC_MCP_RET_ERR_ALREADY_MAPPED = 7, /**< The memory block has already been mapped before. */ 57 MC_MCP_RET_ERR_INVALID_PARAM = 8, /**< Alignment or length error in the command parameters. */ 58 MC_MCP_RET_ERR_OUT_OF_RESOURCES = 9, /**< No space left in the virtual address space of the session. */ 59 MC_MCP_RET_ERR_INVALID_WSM = 10, /**< WSM type unknown or broken WSM */ 60 MC_MCP_RET_ERR_UNKNOWN = 11, /**< unknown error. */ 61 MC_MCP_RET_ERR_INVALID_MAPPING_LENGTH = 12, /**< Lenght of map invalid */ 62 MC_MCP_RET_ERR_MAPPING_TARGET = 13, /**< Map can only be applied to Trustlet session */ 63 MC_MCP_RET_ERR_OUT_OF_CRYPTO_RESSOURCES = 14, /**< Couldn't open crypto session. */ 64 MC_MCP_RET_ERR_SIGNATURE_VERIFICATION_FAILED = 15, /**< System Trustlet signature verification failed. */ 65 MC_MCP_RET_ERR_WRONG_PUBLIC_KEY = 16, /**< System Trustlet public key is wrong. */ 66 MC_MCP_RET_ERR_CONTAINER_TYPE_MISMATCH = 17, /**< Wrong containter type(s). */ 67 MC_MCP_RET_ERR_CONTAINER_LOCKED = 18, /**< Container is locked (or not activated). */ 68 MC_MCP_RET_ERR_SP_NO_CHILD = 19, /**< SPID is not registered with root container. */ 69 MC_MCP_RET_ERR_TL_NO_CHILD = 20, /**< UUID is not registered with sp container. */ 70 MC_MCP_RET_ERR_UNWRAP_ROOT_FAILED = 21, /**< Unwrapping of root container failed. */ 71 MC_MCP_RET_ERR_UNWRAP_SP_FAILED = 22, /**< Unwrapping of service provider container failed. */ 72 MC_MCP_RET_ERR_UNWRAP_TRUSTLET_FAILED = 23, /**< Unwrapping of Trustlet container failed. */ 73 MC_MCP_RET_ERR_CONTAINER_VERSION_MISMATCH = 24, /**< Container version mismatch. */ 74 MC_MCP_RET_ERR_SP_TL_DECRYPTION_FAILED = 25, /**< Decryption of service provider trustlet failed. */ 75 MC_MCP_RET_ERR_SP_TL_HASH_CHECK_FAILED = 26, /**< Hash check of service provider trustlet failed. */ 76 MC_MCP_RET_ERR_LAUNCH_TASK_FAILED = 27, /**< Activation/starting of task failed. */ 77 78 // used for command verification 79 MC_MCP_RET_ERR_UNKNOWN_COMMAND = 50, /**< The command is unknown. */ 80 MC_MCP_RET_ERR_INVALID_DATA = 51 /**< The command data is invalid. */ 81 } mcpResult_t; 82 83 /** Possible MCP Command IDs 84 * Command ID must be between 0 and 0x7FFFFFFF. 85 */ 86 typedef enum { 87 MC_MCP_CMD_ID_INVALID = 0x00000000, /**< Invalid command ID. */ 88 // Session commands 89 MC_MCP_CMD_OPEN_SESSION = 0x00000001, /**< Open a session to a service. */ 90 MC_MCP_CMD_CLOSE_SESSION = 0x00000003, /**< Close an existing service session. */ 91 MC_MCP_CMD_MAP = 0x00000004, /**< Map a block of WSM to a session. */ 92 MC_MCP_CMD_UNMAP = 0x00000005, /**< Unmap a block of WSM from a session. */ 93 MC_MCP_CMD_SUSPEND = 0x00000006, /**< Prepare MobiCore for suspend. */ 94 MC_MCP_CMD_RESUME = 0x00000007, /**< Resume MobiCore from suspension. */ 95 MC_MCP_CMD_DONATE_RAM = 0x00000008, /**< Donate RAM to MobiCore. */ 96 MC_MCP_CMD_GET_MOBICORE_VERSION = 0x00000009, /**< Get MobiCore version information. */ 97 } mcpCmdId_t; 98 99 100 #define FLAG_RESPONSE (1U << 31) /**< Flag to indicate that this is the response to a MCP command. */ 101 102 103 /** Types of WSM known to the MobiCore. 104 */ 105 typedef enum { 106 WSM_INVALID = 0, /**< Invalid memory type */ 107 WSM_CONTIGUOUS = 1, /**< Reference to WSM points to a contiguous region of pages. */ 108 WSM_L2 = 2, /**< Reference to WSM points to an L2 table describing the memory region to share */ 109 }wsmType_t; 110 111 /** Types of RAM known to the MobiCore. 112 */ 113 typedef enum { 114 RAM_INVALID = 0, /**< Invalid memory type */ 115 RAM_GENERIC = 1, /**< Generic RAM of no special type. */ 116 }ramType_t; 117 118 /** Command header. 119 * It just contains the command ID. Only values specified in mcpCmdId_t are allowed as command IDs. 120 * If the command ID is unspecified the MobiCore returns an empty response with the result set to MC_MCP_RET_ERR_UNKNOWN_COMMAND . 121 */ 122 typedef struct { 123 mcpCmdId_t cmdId; /**< Command ID of the command */ 124 } commandHeader_t, *commandHeader_ptr; 125 126 /** Response header. 127 * MobiCore will reply to every MCP command with an MCP response. Like the MCP command the response consists of a 128 * header followed by response data. The response is written to the same memory location as the MCP command. 129 */ 130 typedef struct { 131 uint32_t rspId; /**< Command ID | FLAG_RESPONSE. */ 132 mcpResult_t result; /**< Result informs about the execution result of the command associated with the response. */ 133 } responseHeader_t, *responseHeader_ptr; 134 135 136 137 /** @defgroup CMD MCP Commands 138 * @{ */ 139 140 /** @defgroup ASMCMD Administrative Commands 141 * @{ */ 142 143 /** @defgroup MCPDONATERAM DONATE_RAM 144 * Donate NWd RAM to MobiCore. 145 * This is a debug feature that is not available in release version. 146 * 147 * @{ */ 148 149 /** Donate RAM Command */ 150 typedef struct { 151 commandHeader_t cmdHeader; /**< Command header. */ 152 ramType_t ramType; /**< Type of RAM used for memory pool */ 153 uint32_t adrBuffer; /**< Physical address of the page range*/ 154 uint32_t numPages; /**< Number of pages contained in the donation. */ 155 } mcpCmdDonateRam_t, *mcpCmdDonateRam_ptr; 156 157 /** Donate RAM Command Response */ 158 typedef struct { 159 responseHeader_t rspHeader; /**< Response header. */ 160 } mcpRspDonateRam_t, *mcpRspDonateRam_ptr; 161 /** @} */// End MCPDONATERAM 162 163 164 /** @defgroup MCPGETMOBICOREVERSION GET_MOBICORE_VERSION 165 * Get MobiCore version info. 166 * 167 * @{ */ 168 169 /** Get MobiCore Version Command. */ 170 typedef struct { 171 commandHeader_t cmdHeader; /** Command header. */ 172 } mcpCmdGetMobiCoreVersion_t, *mcpCmdGetMobiCoreVersion_ptr; 173 174 /** Get MobiCore Version Command Response. */ 175 typedef struct { 176 responseHeader_t rspHeader; /** Response header. */ 177 mcVersionInfo_t versionInfo; /** MobiCore version info. */ 178 } mcpRspGetMobiCoreVersion_t, *mcpRspGetMobiCoreVersion_ptr; 179 180 /** @} */// End MCPGETMOBICOREVERSION 181 182 /** @} */// End ASMCMD 183 184 185 /** @defgroup POWERCMD Power Management Commands 186 * @{ */ 187 188 /** @defgroup MCPSUSPEND SUSPEND 189 * Prepare MobiCore suspension. 190 * This command allows MobiCore and MobiCore drivers to release or clean resources and save device state. 191 * 192 * @{ */ 193 194 /** Suspend Command */ 195 typedef struct { 196 commandHeader_t cmdHeader; /**< Command header. */ 197 } mcpCmdSuspend_t, *mcpCmdSuspend_ptr; 198 199 /** Suspend Command Response */ 200 typedef struct { 201 responseHeader_t rspHeader; /**< Response header. */ 202 } mcpRspSuspend_t, *mcpRspSuspend_ptr; 203 /** @} */// End MCPSUSPEND 204 205 206 /** @defgroup MCPRESUME RESUME 207 * Resume MobiCore from suspension. 208 * This command allows MobiCore and MobiCore drivers to reinitialize hardware affected by suspension. 209 * 210 * @{ */ 211 212 /** Resume Command */ 213 typedef struct { 214 commandHeader_t cmdHeader; /**< Command header. */ 215 } mcpCmdResume_t, *mcpCmdResume_ptr; 216 217 /** Resume Command Response */ 218 typedef struct { 219 responseHeader_t rspHeader; /**< Response header. */ 220 } mcpRspResume_t, *mcpRspResume_ptr; 221 222 /** @} */// End MCPRESUME 223 224 /** @} */// End POWERCMD 225 226 227 228 /** @defgroup SESSCMD Session Management Commands 229 * @{ */ 230 231 /** @defgroup MCPOPEN OPEN 232 * Load and open a session to a Trustlet. 233 * The OPEN command loads Trustlet data to the MobiCore context and opens a session to the Trustlet. 234 * If wsmTypeLoadData is WSM_INVALID MobiCore tries to start a pre-installed Trustlet 235 * associated with the uuid passed. 236 * The uuid passed must match the uuid contained in the load data (if available). 237 * On success, MobiCore returns the session ID which can be used for further communication. 238 * @{ */ 239 240 /** Open Command */ 241 typedef struct { 242 commandHeader_t cmdHeader; /**< Command header. */ 243 mcUuid_t uuid; /**< Byte array containing the service UUID. */ 244 wsmType_t wsmTypeTci; /**< Type of WSM used for the TCI */ 245 uint32_t adrTciBuffer; /**< Physical address of the TCI */ 246 uint32_t ofsTciBuffer; /**< Offset to the data. */ 247 uint32_t lenTciBuffer; /**< Length of the TCI. */ 248 wsmType_t wsmTypeLoadData; /**< Type of the memory containing the data to load. */ 249 uint32_t adrLoadData; /**< Physical address of the data to load. */ 250 uint32_t ofsLoadData; /**< Offset to the data. */ 251 uint32_t lenLoadData; /**< Length of the data to load. */ 252 mclfHeader_t tlHeader; /**< Service header. */ 253 } mcpCmdOpen_t, *mcpCmdOpen_ptr; 254 255 /** Open Command Response */ 256 typedef struct { 257 responseHeader_t rspHeader; /**< Response header. */ 258 uint32_t sessionId; /**< Session ID used for further communication. */ 259 } mcpRspOpen_t, *mcpRspOpen_ptr; 260 261 /** @} */// End MCPOPEN 262 263 264 /** @defgroup MCPCLOSE CLOSE 265 * Close an existing session to a Trustlet. 266 * The CLOSE command terminates a session and frees all resources in the MobiCore system which 267 * are currently occupied by the session. Before closing the session, the MobiCore runtime 268 * management waits until all pending operations, like calls to drivers, invoked by the Trustlet 269 * have been terminated. 270 * Mapped memory will automatically be unmapped from the MobiCore context. The NWd is responsible for 271 * processing the freed memory according to the Rich-OS needs. 272 * 273 * @{ */ 274 275 /** Close Command */ 276 typedef struct { 277 commandHeader_t cmdHeader; /**< Command header. */ 278 uint32_t sessionId; /**< Session ID. */ 279 } mcpCmdClose_t, *mcpCmdClose_ptr; 280 281 /** Close Command Response */ 282 typedef struct { 283 responseHeader_t rspHeader; /**< Response header. */ 284 } mcpRspClose_t, *mcpRspClose_ptr; 285 286 /** @} */// End MCPCLOSE 287 288 289 /** @defgroup MCPMAP MAP 290 * Map a portion of memory to a session. 291 * The MAP command provides a block of memory to the context of a service. 292 * The memory then becomes world-shared memory (WSM). 293 * The WSM can either be normal anonymous memory from malloc() or be a 294 * block of page aligned, contiguous memory. 295 * The only allowed memory type here is WSM_L2. 296 * @{ */ 297 298 /** Map Command */ 299 typedef struct { 300 commandHeader_t cmdHeader; /**< Command header. */ 301 uint32_t sessionId; /**< Session ID of a valid session */ 302 wsmType_t wsmType; /**< Type of WSM used of the memory*/ 303 uint32_t adrBuffer; /**< Physical address of the memory */ 304 uint32_t ofsBuffer; /**< Offset to the payload. */ 305 uint32_t lenBuffer; /**< Length of the buffer. */ 306 } mcpCmdMap_t, *mcpCmdMap_ptr; 307 308 #define MCP_MAP_MAX 0x100000 /**< Maximum allowed length for MCP map. */ 309 310 /** Map Command Response */ 311 typedef struct { 312 responseHeader_t rspHeader; /**< Response header. */ 313 uint32_t secureVirtualAdr; /**< Virtual address in the context of the service the WSM is mapped to, already includes a possible offset! */ 314 } mcpRspMap_t, *mcpRspMap_ptr; 315 316 /** @} *///End MCPMAP 317 318 319 /** @defgroup MCPUNMAP UNMAP 320 * Unmap a portion of world-shared memory from a session. 321 * The UNMAP command is used to unmap a previously mapped block of 322 * world shared memory from the context of a session. 323 * 324 * Attention: The memory block will be immediately unmapped from the specified session. 325 * If the service is still accessing the memory, the service will trigger a segmentation fault. 326 * @{ */ 327 328 /** Unmap Command */ 329 typedef struct { 330 commandHeader_t cmdHeader; /**< Command header. */ 331 uint32_t sessionId; /**< Session ID of a valid session */ 332 wsmType_t wsmType; /**< Type of WSM used of the memory*/ 333 uint32_t secureVirtualAdr; /**< Virtual address in the context of the service the WSM has been mapped to, already includes a possible offset! */ 334 uint32_t lenVirtualBuffer; /**< Length of the virtual buffer. */ 335 } mcpCmdUnmap_t, *mcpCmdUnmap_ptr; 336 337 /** Unmap Command Response */ 338 typedef struct { 339 responseHeader_t rspHeader; /**< Response header. */ 340 } mcpRspUnmap_t, *mcpRspUnmap_ptr; 341 342 /** @} */// End MCPUNMAP 343 344 /** @} */// End SESSCMD 345 346 /** @} */// End CMD 347 348 /** Structure of the MCP buffer. */ 349 typedef union { 350 commandHeader_t cmdHeader; /**< Command header. */ 351 responseHeader_t rspHeader; /**< Response header. */ 352 mcpCmdOpen_t cmdOpen; /**< Load and open service. */ 353 mcpRspOpen_t rspOpen; /**< Response to load and open service. */ 354 mcpCmdClose_t cmdClose; /**< Close command. */ 355 mcpRspClose_t rspClose; /**< Response to close command. */ 356 mcpCmdMap_t cmdMap; /**< Map WSM to service context. */ 357 mcpRspMap_t rspMap; /**< Response to MAP command. */ 358 mcpCmdUnmap_t cmdUnmap; /**< Unmap WSM from service context. */ 359 mcpRspUnmap_t rspUnmap; /**< Response to UNMAP command. */ 360 mcpCmdSuspend_t cmdSuspend; /**< Suspend MobiCore. */ 361 mcpRspSuspend_t rspSuspend; /**< Response to SUSPEND command. */ 362 mcpCmdResume_t cmdResume; /**< Resume MobiCore. */ 363 mcpRspResume_t rspResume; /**< Response to RESUME command. */ 364 mcpCmdDonateRam_t cmdDonateRam; /**< Donate RAM to MobiCore. */ 365 mcpRspDonateRam_t rspDonateRam; /**< Response to DONATE_RAM command. */ 366 mcpCmdGetMobiCoreVersion_t cmdGetMobiCoreVersion; /**< Get MobiCore Version command. */ 367 mcpRspGetMobiCoreVersion_t rspGetMobiCoreVersion; /**< Response to GET_MOBICORE_VERSION command. */ 368 } mcpMessage_t, *mcpMessage_ptr; 369 370 371 #define MIN_MCP_LEN sizeof(mcpMessage_t) /**< Minimum MCP buffer length (in bytes). */ 372 373 #define MC_FLAG_NO_SLEEP_REQ 0 374 #define MC_FLAG_REQ_TO_SLEEP 1 375 376 #define MC_STATE_NORMAL_EXECUTION 0 377 #define MC_STATE_READY_TO_SLEEP 1 378 379 typedef struct { 380 uint16_t SleepReq; 381 uint16_t ReadyToSleep; 382 } mcSleepMod_t, *mcSleepMod_ptr; 383 384 /** MobiCore status flags */ 385 typedef struct { 386 uint32_t schedule; /**< Scheduling hint: if <> MC_FLAG_SCHEDULE_IDLE, MobiCore should be scheduled by the NWd */ 387 mcSleepMod_t sleepMode; /**< */ 388 uint32_t RFU2; /**< Reserved for future use: Must not be interpreted */ 389 uint32_t RFU3; /**< Reserved for future use: Must not be interpreted */ 390 } mcFlags_t, *mcFlags_ptr; 391 392 #define MC_FLAG_SCHEDULE_IDLE 0 /**< MobiCore is idle. No scheduling required. */ 393 #define MC_FLAG_SCHEDULE_NON_IDLE 1 /**< MobiCore is non idle, scheduling is required. */ 394 395 396 397 /** MCP buffer structure */ 398 typedef struct { 399 mcFlags_t mcFlags; /**< MobiCore Flags */ 400 mcpMessage_t mcpMessage; /**< MCP message buffer */ 401 } mcpBuffer_t, *mcpBuffer_ptr; 402 403 /** @} */ 404 #endif /* MCP_H_ */ 405