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