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 */ 48typedef 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 */ 86typedef 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 */ 105typedef 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 */ 113typedef 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 */ 122typedef 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 */ 130typedef 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 */ 150typedef 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 */ 158typedef 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. */ 170typedef struct { 171 commandHeader_t cmdHeader; /** Command header. */ 172} mcpCmdGetMobiCoreVersion_t, *mcpCmdGetMobiCoreVersion_ptr; 173 174/** Get MobiCore Version Command Response. */ 175typedef 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 */ 195typedef struct { 196 commandHeader_t cmdHeader; /**< Command header. */ 197} mcpCmdSuspend_t, *mcpCmdSuspend_ptr; 198 199/** Suspend Command Response */ 200typedef 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 */ 213typedef struct { 214 commandHeader_t cmdHeader; /**< Command header. */ 215} mcpCmdResume_t, *mcpCmdResume_ptr; 216 217/** Resume Command Response */ 218typedef 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 */ 241typedef 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 */ 256typedef 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 */ 276typedef struct { 277 commandHeader_t cmdHeader; /**< Command header. */ 278 uint32_t sessionId; /**< Session ID. */ 279} mcpCmdClose_t, *mcpCmdClose_ptr; 280 281/** Close Command Response */ 282typedef 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 */ 299typedef 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 */ 311typedef 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 */ 329typedef 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 */ 338typedef 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. */ 349typedef 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 379typedef struct { 380 uint16_t SleepReq; 381 uint16_t ReadyToSleep; 382} mcSleepMod_t, *mcSleepMod_ptr; 383 384/** MobiCore status flags */ 385typedef 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 */ 398typedef 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