| /** @addtogroup MCP | |
| * @{ | |
| * The MCP defines commands and responses which are used to control the MobiCore system. | |
| * MCP information is exchanged in a world share memory buffer which has been established prior between NWd | |
| * and SWd using the FastCall interface. The buffer needs to be provided by the MobiCore driver and is utilized | |
| * to send MCP commands to the MobiCore as well as receiving responses from the MobiCore. | |
| * The command of the normal world will be overwritten with the response from the secure side. | |
| * | |
| * @file | |
| * MCP command interface definitions. | |
| * | |
| * <!-- Copyright Giesecke & Devrient GmbH 2009-2012 --> | |
| * | |
| * Redistribution and use in source and binary forms, with or without | |
| * modification, are permitted provided that the following conditions | |
| * are met: | |
| * 1. Redistributions of source code must retain the above copyright | |
| * notice, this list of conditions and the following disclaimer. | |
| * 2. Redistributions in binary form must reproduce the above copyright | |
| * notice, this list of conditions and the following disclaimer in the | |
| * documentation and/or other materials provided with the distribution. | |
| * 3. The name of the author may not be used to endorse or promote | |
| * products derived from this software without specific prior | |
| * written permission. | |
| * | |
| * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS | |
| * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED | |
| * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
| * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY | |
| * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
| * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE | |
| * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS | |
| * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, | |
| * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING | |
| * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS | |
| * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
| */ | |
| #ifndef MCP_H_ | |
| #define MCP_H_ | |
| #include "mcUuid.h" | |
| #include "mcLoadFormat.h" | |
| #include "mcVersionInfo.h" | |
| /** MobiCore Return Code Defines. | |
| * List of the possible MobiCore return codes. | |
| */ | |
| typedef enum { | |
| MC_MCP_RET_OK = 0, /**< Memory has successfully been mapped. */ | |
| MC_MCP_RET_ERR_INVALID_SESSION = 1, /**< The session ID is invalid. */ | |
| MC_MCP_RET_ERR_UNKNOWN_UUID = 2, /**< The UUID of the Trustlet is unknown. */ | |
| MC_MCP_RET_ERR_UNKNOWN_DRIVER_ID = 3, /**< The ID of the driver is unknown. */ | |
| MC_MCP_RET_ERR_NO_MORE_SESSIONS = 4, /**< No more session are allowed. */ | |
| MC_MCP_RET_ERR_CONTAINER_INVALID = 5, /**< The container is invalid. */ | |
| MC_MCP_RET_ERR_TRUSTLET_INVALID = 6, /**< The Trustlet is invalid. */ | |
| MC_MCP_RET_ERR_ALREADY_MAPPED = 7, /**< The memory block has already been mapped before. */ | |
| MC_MCP_RET_ERR_INVALID_PARAM = 8, /**< Alignment or length error in the command parameters. */ | |
| MC_MCP_RET_ERR_OUT_OF_RESOURCES = 9, /**< No space left in the virtual address space of the session. */ | |
| MC_MCP_RET_ERR_INVALID_WSM = 10, /**< WSM type unknown or broken WSM */ | |
| MC_MCP_RET_ERR_UNKNOWN = 11, /**< unknown error. */ | |
| MC_MCP_RET_ERR_INVALID_MAPPING_LENGTH = 12, /**< Lenght of map invalid */ | |
| MC_MCP_RET_ERR_MAPPING_TARGET = 13, /**< Map can only be applied to Trustlet session */ | |
| MC_MCP_RET_ERR_OUT_OF_CRYPTO_RESSOURCES = 14, /**< Couldn't open crypto session. */ | |
| MC_MCP_RET_ERR_SIGNATURE_VERIFICATION_FAILED = 15, /**< System Trustlet signature verification failed. */ | |
| MC_MCP_RET_ERR_WRONG_PUBLIC_KEY = 16, /**< System Trustlet public key is wrong. */ | |
| MC_MCP_RET_ERR_CONTAINER_TYPE_MISMATCH = 17, /**< Wrong containter type(s). */ | |
| MC_MCP_RET_ERR_CONTAINER_LOCKED = 18, /**< Container is locked (or not activated). */ | |
| MC_MCP_RET_ERR_SP_NO_CHILD = 19, /**< SPID is not registered with root container. */ | |
| MC_MCP_RET_ERR_TL_NO_CHILD = 20, /**< UUID is not registered with sp container. */ | |
| MC_MCP_RET_ERR_UNWRAP_ROOT_FAILED = 21, /**< Unwrapping of root container failed. */ | |
| MC_MCP_RET_ERR_UNWRAP_SP_FAILED = 22, /**< Unwrapping of service provider container failed. */ | |
| MC_MCP_RET_ERR_UNWRAP_TRUSTLET_FAILED = 23, /**< Unwrapping of Trustlet container failed. */ | |
| MC_MCP_RET_ERR_CONTAINER_VERSION_MISMATCH = 24, /**< Container version mismatch. */ | |
| MC_MCP_RET_ERR_SP_TL_DECRYPTION_FAILED = 25, /**< Decryption of service provider trustlet failed. */ | |
| MC_MCP_RET_ERR_SP_TL_HASH_CHECK_FAILED = 26, /**< Hash check of service provider trustlet failed. */ | |
| MC_MCP_RET_ERR_LAUNCH_TASK_FAILED = 27, /**< Activation/starting of task failed. */ | |
| // used for command verification | |
| MC_MCP_RET_ERR_UNKNOWN_COMMAND = 50, /**< The command is unknown. */ | |
| MC_MCP_RET_ERR_INVALID_DATA = 51 /**< The command data is invalid. */ | |
| } mcpResult_t; | |
| /** Possible MCP Command IDs | |
| * Command ID must be between 0 and 0x7FFFFFFF. | |
| */ | |
| typedef enum { | |
| MC_MCP_CMD_ID_INVALID = 0x00000000, /**< Invalid command ID. */ | |
| // Session commands | |
| MC_MCP_CMD_OPEN_SESSION = 0x00000001, /**< Open a session to a service. */ | |
| MC_MCP_CMD_CLOSE_SESSION = 0x00000003, /**< Close an existing service session. */ | |
| MC_MCP_CMD_MAP = 0x00000004, /**< Map a block of WSM to a session. */ | |
| MC_MCP_CMD_UNMAP = 0x00000005, /**< Unmap a block of WSM from a session. */ | |
| MC_MCP_CMD_SUSPEND = 0x00000006, /**< Prepare MobiCore for suspend. */ | |
| MC_MCP_CMD_RESUME = 0x00000007, /**< Resume MobiCore from suspension. */ | |
| MC_MCP_CMD_DONATE_RAM = 0x00000008, /**< Donate RAM to MobiCore. */ | |
| MC_MCP_CMD_GET_MOBICORE_VERSION = 0x00000009, /**< Get MobiCore version information. */ | |
| } mcpCmdId_t; | |
| #define FLAG_RESPONSE (1U << 31) /**< Flag to indicate that this is the response to a MCP command. */ | |
| /** Types of WSM known to the MobiCore. | |
| */ | |
| typedef enum { | |
| WSM_INVALID = 0, /**< Invalid memory type */ | |
| WSM_CONTIGUOUS = 1, /**< Reference to WSM points to a contiguous region of pages. */ | |
| WSM_L2 = 2, /**< Reference to WSM points to an L2 table describing the memory region to share */ | |
| }wsmType_t; | |
| /** Types of RAM known to the MobiCore. | |
| */ | |
| typedef enum { | |
| RAM_INVALID = 0, /**< Invalid memory type */ | |
| RAM_GENERIC = 1, /**< Generic RAM of no special type. */ | |
| }ramType_t; | |
| /** Command header. | |
| * It just contains the command ID. Only values specified in mcpCmdId_t are allowed as command IDs. | |
| * If the command ID is unspecified the MobiCore returns an empty response with the result set to MC_MCP_RET_ERR_UNKNOWN_COMMAND . | |
| */ | |
| typedef struct { | |
| mcpCmdId_t cmdId; /**< Command ID of the command */ | |
| } commandHeader_t, *commandHeader_ptr; | |
| /** Response header. | |
| * MobiCore will reply to every MCP command with an MCP response. Like the MCP command the response consists of a | |
| * header followed by response data. The response is written to the same memory location as the MCP command. | |
| */ | |
| typedef struct { | |
| uint32_t rspId; /**< Command ID | FLAG_RESPONSE. */ | |
| mcpResult_t result; /**< Result informs about the execution result of the command associated with the response. */ | |
| } responseHeader_t, *responseHeader_ptr; | |
| /** @defgroup CMD MCP Commands | |
| * @{ */ | |
| /** @defgroup ASMCMD Administrative Commands | |
| * @{ */ | |
| /** @defgroup MCPDONATERAM DONATE_RAM | |
| * Donate NWd RAM to MobiCore. | |
| * This is a debug feature that is not available in release version. | |
| * | |
| * @{ */ | |
| /** Donate RAM Command */ | |
| typedef struct { | |
| commandHeader_t cmdHeader; /**< Command header. */ | |
| ramType_t ramType; /**< Type of RAM used for memory pool */ | |
| uint32_t adrBuffer; /**< Physical address of the page range*/ | |
| uint32_t numPages; /**< Number of pages contained in the donation. */ | |
| } mcpCmdDonateRam_t, *mcpCmdDonateRam_ptr; | |
| /** Donate RAM Command Response */ | |
| typedef struct { | |
| responseHeader_t rspHeader; /**< Response header. */ | |
| } mcpRspDonateRam_t, *mcpRspDonateRam_ptr; | |
| /** @} */// End MCPDONATERAM | |
| /** @defgroup MCPGETMOBICOREVERSION GET_MOBICORE_VERSION | |
| * Get MobiCore version info. | |
| * | |
| * @{ */ | |
| /** Get MobiCore Version Command. */ | |
| typedef struct { | |
| commandHeader_t cmdHeader; /** Command header. */ | |
| } mcpCmdGetMobiCoreVersion_t, *mcpCmdGetMobiCoreVersion_ptr; | |
| /** Get MobiCore Version Command Response. */ | |
| typedef struct { | |
| responseHeader_t rspHeader; /** Response header. */ | |
| mcVersionInfo_t versionInfo; /** MobiCore version info. */ | |
| } mcpRspGetMobiCoreVersion_t, *mcpRspGetMobiCoreVersion_ptr; | |
| /** @} */// End MCPGETMOBICOREVERSION | |
| /** @} */// End ASMCMD | |
| /** @defgroup POWERCMD Power Management Commands | |
| * @{ */ | |
| /** @defgroup MCPSUSPEND SUSPEND | |
| * Prepare MobiCore suspension. | |
| * This command allows MobiCore and MobiCore drivers to release or clean resources and save device state. | |
| * | |
| * @{ */ | |
| /** Suspend Command */ | |
| typedef struct { | |
| commandHeader_t cmdHeader; /**< Command header. */ | |
| } mcpCmdSuspend_t, *mcpCmdSuspend_ptr; | |
| /** Suspend Command Response */ | |
| typedef struct { | |
| responseHeader_t rspHeader; /**< Response header. */ | |
| } mcpRspSuspend_t, *mcpRspSuspend_ptr; | |
| /** @} */// End MCPSUSPEND | |
| /** @defgroup MCPRESUME RESUME | |
| * Resume MobiCore from suspension. | |
| * This command allows MobiCore and MobiCore drivers to reinitialize hardware affected by suspension. | |
| * | |
| * @{ */ | |
| /** Resume Command */ | |
| typedef struct { | |
| commandHeader_t cmdHeader; /**< Command header. */ | |
| } mcpCmdResume_t, *mcpCmdResume_ptr; | |
| /** Resume Command Response */ | |
| typedef struct { | |
| responseHeader_t rspHeader; /**< Response header. */ | |
| } mcpRspResume_t, *mcpRspResume_ptr; | |
| /** @} */// End MCPRESUME | |
| /** @} */// End POWERCMD | |
| /** @defgroup SESSCMD Session Management Commands | |
| * @{ */ | |
| /** @defgroup MCPOPEN OPEN | |
| * Load and open a session to a Trustlet. | |
| * The OPEN command loads Trustlet data to the MobiCore context and opens a session to the Trustlet. | |
| * If wsmTypeLoadData is WSM_INVALID MobiCore tries to start a pre-installed Trustlet | |
| * associated with the uuid passed. | |
| * The uuid passed must match the uuid contained in the load data (if available). | |
| * On success, MobiCore returns the session ID which can be used for further communication. | |
| * @{ */ | |
| /** Open Command */ | |
| typedef struct { | |
| commandHeader_t cmdHeader; /**< Command header. */ | |
| mcUuid_t uuid; /**< Byte array containing the service UUID. */ | |
| wsmType_t wsmTypeTci; /**< Type of WSM used for the TCI */ | |
| uint32_t adrTciBuffer; /**< Physical address of the TCI */ | |
| uint32_t ofsTciBuffer; /**< Offset to the data. */ | |
| uint32_t lenTciBuffer; /**< Length of the TCI. */ | |
| wsmType_t wsmTypeLoadData; /**< Type of the memory containing the data to load. */ | |
| uint32_t adrLoadData; /**< Physical address of the data to load. */ | |
| uint32_t ofsLoadData; /**< Offset to the data. */ | |
| uint32_t lenLoadData; /**< Length of the data to load. */ | |
| mclfHeader_t tlHeader; /**< Service header. */ | |
| } mcpCmdOpen_t, *mcpCmdOpen_ptr; | |
| /** Open Command Response */ | |
| typedef struct { | |
| responseHeader_t rspHeader; /**< Response header. */ | |
| uint32_t sessionId; /**< Session ID used for further communication. */ | |
| } mcpRspOpen_t, *mcpRspOpen_ptr; | |
| /** @} */// End MCPOPEN | |
| /** @defgroup MCPCLOSE CLOSE | |
| * Close an existing session to a Trustlet. | |
| * The CLOSE command terminates a session and frees all resources in the MobiCore system which | |
| * are currently occupied by the session. Before closing the session, the MobiCore runtime | |
| * management waits until all pending operations, like calls to drivers, invoked by the Trustlet | |
| * have been terminated. | |
| * Mapped memory will automatically be unmapped from the MobiCore context. The NWd is responsible for | |
| * processing the freed memory according to the Rich-OS needs. | |
| * | |
| * @{ */ | |
| /** Close Command */ | |
| typedef struct { | |
| commandHeader_t cmdHeader; /**< Command header. */ | |
| uint32_t sessionId; /**< Session ID. */ | |
| } mcpCmdClose_t, *mcpCmdClose_ptr; | |
| /** Close Command Response */ | |
| typedef struct { | |
| responseHeader_t rspHeader; /**< Response header. */ | |
| } mcpRspClose_t, *mcpRspClose_ptr; | |
| /** @} */// End MCPCLOSE | |
| /** @defgroup MCPMAP MAP | |
| * Map a portion of memory to a session. | |
| * The MAP command provides a block of memory to the context of a service. | |
| * The memory then becomes world-shared memory (WSM). | |
| * The WSM can either be normal anonymous memory from malloc() or be a | |
| * block of page aligned, contiguous memory. | |
| * The only allowed memory type here is WSM_L2. | |
| * @{ */ | |
| /** Map Command */ | |
| typedef struct { | |
| commandHeader_t cmdHeader; /**< Command header. */ | |
| uint32_t sessionId; /**< Session ID of a valid session */ | |
| wsmType_t wsmType; /**< Type of WSM used of the memory*/ | |
| uint32_t adrBuffer; /**< Physical address of the memory */ | |
| uint32_t ofsBuffer; /**< Offset to the payload. */ | |
| uint32_t lenBuffer; /**< Length of the buffer. */ | |
| } mcpCmdMap_t, *mcpCmdMap_ptr; | |
| #define MCP_MAP_MAX 0x100000 /**< Maximum allowed length for MCP map. */ | |
| /** Map Command Response */ | |
| typedef struct { | |
| responseHeader_t rspHeader; /**< Response header. */ | |
| uint32_t secureVirtualAdr; /**< Virtual address in the context of the service the WSM is mapped to, already includes a possible offset! */ | |
| } mcpRspMap_t, *mcpRspMap_ptr; | |
| /** @} *///End MCPMAP | |
| /** @defgroup MCPUNMAP UNMAP | |
| * Unmap a portion of world-shared memory from a session. | |
| * The UNMAP command is used to unmap a previously mapped block of | |
| * world shared memory from the context of a session. | |
| * | |
| * Attention: The memory block will be immediately unmapped from the specified session. | |
| * If the service is still accessing the memory, the service will trigger a segmentation fault. | |
| * @{ */ | |
| /** Unmap Command */ | |
| typedef struct { | |
| commandHeader_t cmdHeader; /**< Command header. */ | |
| uint32_t sessionId; /**< Session ID of a valid session */ | |
| wsmType_t wsmType; /**< Type of WSM used of the memory*/ | |
| uint32_t secureVirtualAdr; /**< Virtual address in the context of the service the WSM has been mapped to, already includes a possible offset! */ | |
| uint32_t lenVirtualBuffer; /**< Length of the virtual buffer. */ | |
| } mcpCmdUnmap_t, *mcpCmdUnmap_ptr; | |
| /** Unmap Command Response */ | |
| typedef struct { | |
| responseHeader_t rspHeader; /**< Response header. */ | |
| } mcpRspUnmap_t, *mcpRspUnmap_ptr; | |
| /** @} */// End MCPUNMAP | |
| /** @} */// End SESSCMD | |
| /** @} */// End CMD | |
| /** Structure of the MCP buffer. */ | |
| typedef union { | |
| commandHeader_t cmdHeader; /**< Command header. */ | |
| responseHeader_t rspHeader; /**< Response header. */ | |
| mcpCmdOpen_t cmdOpen; /**< Load and open service. */ | |
| mcpRspOpen_t rspOpen; /**< Response to load and open service. */ | |
| mcpCmdClose_t cmdClose; /**< Close command. */ | |
| mcpRspClose_t rspClose; /**< Response to close command. */ | |
| mcpCmdMap_t cmdMap; /**< Map WSM to service context. */ | |
| mcpRspMap_t rspMap; /**< Response to MAP command. */ | |
| mcpCmdUnmap_t cmdUnmap; /**< Unmap WSM from service context. */ | |
| mcpRspUnmap_t rspUnmap; /**< Response to UNMAP command. */ | |
| mcpCmdSuspend_t cmdSuspend; /**< Suspend MobiCore. */ | |
| mcpRspSuspend_t rspSuspend; /**< Response to SUSPEND command. */ | |
| mcpCmdResume_t cmdResume; /**< Resume MobiCore. */ | |
| mcpRspResume_t rspResume; /**< Response to RESUME command. */ | |
| mcpCmdDonateRam_t cmdDonateRam; /**< Donate RAM to MobiCore. */ | |
| mcpRspDonateRam_t rspDonateRam; /**< Response to DONATE_RAM command. */ | |
| mcpCmdGetMobiCoreVersion_t cmdGetMobiCoreVersion; /**< Get MobiCore Version command. */ | |
| mcpRspGetMobiCoreVersion_t rspGetMobiCoreVersion; /**< Response to GET_MOBICORE_VERSION command. */ | |
| } mcpMessage_t, *mcpMessage_ptr; | |
| #define MIN_MCP_LEN sizeof(mcpMessage_t) /**< Minimum MCP buffer length (in bytes). */ | |
| #define MC_FLAG_NO_SLEEP_REQ 0 | |
| #define MC_FLAG_REQ_TO_SLEEP 1 | |
| #define MC_STATE_NORMAL_EXECUTION 0 | |
| #define MC_STATE_READY_TO_SLEEP 1 | |
| typedef struct { | |
| uint16_t SleepReq; | |
| uint16_t ReadyToSleep; | |
| } mcSleepMod_t, *mcSleepMod_ptr; | |
| /** MobiCore status flags */ | |
| typedef struct { | |
| uint32_t schedule; /**< Scheduling hint: if <> MC_FLAG_SCHEDULE_IDLE, MobiCore should be scheduled by the NWd */ | |
| mcSleepMod_t sleepMode; /**< */ | |
| uint32_t RFU2; /**< Reserved for future use: Must not be interpreted */ | |
| uint32_t RFU3; /**< Reserved for future use: Must not be interpreted */ | |
| } mcFlags_t, *mcFlags_ptr; | |
| #define MC_FLAG_SCHEDULE_IDLE 0 /**< MobiCore is idle. No scheduling required. */ | |
| #define MC_FLAG_SCHEDULE_NON_IDLE 1 /**< MobiCore is non idle, scheduling is required. */ | |
| /** MCP buffer structure */ | |
| typedef struct { | |
| mcFlags_t mcFlags; /**< MobiCore Flags */ | |
| mcpMessage_t mcpMessage; /**< MCP message buffer */ | |
| } mcpBuffer_t, *mcpBuffer_ptr; | |
| /** @} */ | |
| #endif /* MCP_H_ */ |