| /** @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_ */ |