1 /** 2 * @defgroup MCD_API MobiCore Driver API 3 * @addtogroup MCD_API 4 * @{ 5 * 6 * @if DOXYGEN_MCDRV_API 7 * @mainpage MobiCore Driver API. 8 * @endif 9 * 10 * MobiCore Driver API. 11 * 12 * The MobiCore (MC) Driver API provides access functions to the MobiCore runtime environment and the contained Trustlets. 13 * 14 * @image html DoxyOverviewDrvApi500x.png 15 * @image latex DoxyOverviewDrvApi500x.png "MobiCore Overview" width=12cm 16 * 17 * <!-- Copyright Giesecke & Devrient GmbH 2009 - 2012 --> 18 * 19 * Redistribution and use in source and binary forms, with or without 20 * modification, are permitted provided that the following conditions 21 * are met: 22 * 1. Redistributions of source code must retain the above copyright 23 * notice, this list of conditions and the following disclaimer. 24 * 2. Redistributions in binary form must reproduce the above copyright 25 * notice, this list of conditions and the following disclaimer in the 26 * documentation and/or other materials provided with the distribution. 27 * 3. The name of the author may not be used to endorse or promote 28 * products derived from this software without specific prior 29 * written permission. 30 * 31 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS 32 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 33 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 34 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY 35 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 36 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 37 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 38 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 39 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 40 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 41 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 42 */ 43 #ifndef MCDRIVER_H_ 44 #define MCDRIVER_H_ 45 46 #if (!defined(__MC_CLIENT_LIB_API)) && __cplusplus 47 #define __MC_CLIENT_LIB_API extern "C" 48 #else 49 #define __MC_CLIENT_LIB_API 50 #endif // __cplusplus 51 52 53 #include <stdint.h> 54 #include <stdbool.h> 55 56 #include "mcUuid.h" 57 #include "mcVersionInfo.h" 58 59 /* 60 * MobiCore driver API error codes. 61 * MAJOR part of error code is stable. 62 * MCP part contains MCP result code. See MCI/mcimcp.h 63 * DETAIL part may be used in testing for specific error code. 64 * 65 * Detail error codes may change in different releases 66 * Please do not test DETAIL part when comparing error codes. 67 */ 68 #define MC_DRV_ERROR_MAJOR(ecode) ((ecode) & 0xFF) /**< Get MAJOR part of error code. */ 69 #define MC_DRV_ERROR_MCP(ecode) (((ecode)>>8) & 0xFF) /**< Get MCP part of error code. */ 70 #define MC_DRV_ERROR_DETAIL(ecode) (((ecode)>>16) & 0x0FFF) /**< Get detail part of error code. */ 71 72 typedef uint32_t mcResult_t; 73 /** 74 * Return values of MobiCore driver functions. 75 */ 76 #define MC_DRV_OK 0x00000000 /**< Function call succeeded. */ 77 #define MC_DRV_NO_NOTIFICATION 0x00000001 /**< No notification available. */ 78 #define MC_DRV_ERR_NOTIFICATION 0x00000002 /**< Error during notification on communication level. */ 79 #define MC_DRV_ERR_NOT_IMPLEMENTED 0x00000003 /**< Function not implemented. */ 80 #define MC_DRV_ERR_OUT_OF_RESOURCES 0x00000004 /**< No more resources available. */ 81 #define MC_DRV_ERR_INIT 0x00000005 /**< Driver initialization failed. */ 82 #define MC_DRV_ERR_UNKNOWN 0x00000006 /**< Unknown error. */ 83 #define MC_DRV_ERR_UNKNOWN_DEVICE 0x00000007 /**< The specified device is unknown. */ 84 #define MC_DRV_ERR_UNKNOWN_SESSION 0x00000008 /**< The specified session is unknown. */ 85 #define MC_DRV_ERR_INVALID_OPERATION 0x00000009 /**< The specified operation is not allowed. */ 86 #define MC_DRV_ERR_INVALID_RESPONSE 0x0000000a /**< The response header from the MC is invalid. */ 87 #define MC_DRV_ERR_TIMEOUT 0x0000000b /**< Function call timed out. */ 88 #define MC_DRV_ERR_NO_FREE_MEMORY 0x0000000c /**< Can not allocate additional memory. */ 89 #define MC_DRV_ERR_FREE_MEMORY_FAILED 0x0000000d /**< Free memory failed. */ 90 #define MC_DRV_ERR_SESSION_PENDING 0x0000000e /**< Still some open sessions pending. */ 91 #define MC_DRV_ERR_DAEMON_UNREACHABLE 0x0000000f /**< MC daemon not reachable */ 92 #define MC_DRV_ERR_INVALID_DEVICE_FILE 0x00000010 /**< The device file of the kernel module could not be opened. */ 93 #define MC_DRV_ERR_INVALID_PARAMETER 0x00000011 /**< Invalid parameter. */ 94 #define MC_DRV_ERR_KERNEL_MODULE 0x00000012 /**< Error from Kernel Module, see DETAIL for errno. */ 95 #define MC_DRV_ERR_BULK_MAPPING 0x00000013 /**< Error during mapping of additional bulk memory to session. */ 96 #define MC_DRV_ERR_BULK_UNMAPPING 0x00000014 /**< Error during unmapping of additional bulk memory to session. */ 97 #define MC_DRV_INFO_NOTIFICATION 0x00000015 /**< Notification received, exit code available. */ 98 #define MC_DRV_ERR_NQ_FAILED 0x00000016 /**< Set up of NWd connection failed. */ 99 100 #define MC_DRV_ERR_DAEMON_VERSION 0x00000017 /**< Wrong daemon version. */ 101 #define MC_DRV_ERR_CONTAINER_VERSION 0x00000018 /**< Wrong container version. */ 102 103 // those should become MCP or even detail codes on top of MC_DRV_ERR_MCP_ERROR 104 #define MC_DRV_ERR_WRONG_PUBLIC_KEY 0x00000019 /**< System Trustlet public key is wrong. */ 105 #define MC_DRV_ERR_CONTAINER_TYPE_MISMATCH 0x0000001a /**< Wrong containter type(s). */ 106 #define MC_DRV_ERR_CONTAINER_LOCKED 0x0000001b /**< Container is locked (or not activated). */ 107 #define MC_DRV_ERR_SP_NO_CHILD 0x0000001c /**< SPID is not registered with root container. */ 108 #define MC_DRV_ERR_TL_NO_CHILD 0x0000001d /**< UUID is not registered with sp container. */ 109 #define MC_DRV_ERR_UNWRAP_ROOT_FAILED 0x0000001e /**< Unwrapping of root container failed. */ 110 #define MC_DRV_ERR_UNWRAP_SP_FAILED 0x0000001f /**< Unwrapping of service provider container failed. */ 111 #define MC_DRV_ERR_UNWRAP_TRUSTLET_FAILED 0x00000020 /**< Unwrapping of Trustlet container failed. */ 112 113 // use separate numbers for those in the future 114 #define MC_DRV_ERR_DEVICE_ALREADY_OPEN MC_DRV_ERR_INVALID_OPERATION /** < Device is already open. */ 115 #define MC_DRV_ERR_SOCKET_CONNECT MC_DRV_ERR_DAEMON_UNREACHABLE /**< MC daemon socket not reachable. */ 116 #define MC_DRV_ERR_SOCKET_WRITE MC_DRV_ERR_DAEMON_UNREACHABLE /**< MC daemon socket write error. */ 117 #define MC_DRV_ERR_SOCKET_READ MC_DRV_ERR_DAEMON_UNREACHABLE /**< MC daemon socket read error. */ 118 #define MC_DRV_ERR_SOCKET_LENGTH MC_DRV_ERR_DAEMON_UNREACHABLE /**< MC daemon socket read error. */ 119 #define MC_DRV_ERR_DAEMON_SOCKET MC_DRV_ERR_DAEMON_UNREACHABLE /**< MC daemon had problems with socket. */ 120 #define MC_DRV_ERR_DEVICE_FILE_OPEN MC_DRV_ERR_INVALID_DEVICE_FILE /**< The device file of the kernel module could not be opened. */ 121 #define MC_DRV_ERR_NULL_POINTER MC_DRV_ERR_INVALID_PARAMETER /**< Null pointer passed as parameter. */ 122 #define MC_DRV_ERR_TCI_TOO_BIG MC_DRV_ERR_INVALID_PARAMETER /**< Requested TCI length is too high. */ 123 #define MC_DRV_ERR_WSM_NOT_FOUND MC_DRV_ERR_INVALID_PARAMETER /**< Requested TCI was not allocated with mallocWsm(). */ 124 #define MC_DRV_ERR_TCI_GREATER_THAN_WSM MC_DRV_ERR_INVALID_PARAMETER /**< Requested TCI length is bigger than allocated WSM. */ 125 #define MC_DRV_ERR_TRUSTLET_NOT_FOUND MC_DRV_ERR_INVALID_DEVICE_FILE /** < Trustlet could not be found in mcRegistry. */ 126 #define MC_DRV_ERR_DAEMON_KMOD_ERROR MC_DRV_ERR_DAEMON_UNREACHABLE /**< Daemon cannot use Kernel module as expected. */ 127 #define MC_DRV_ERR_DAEMON_MCI_ERROR MC_DRV_ERR_DAEMON_UNREACHABLE /**< Daemon cannot use MCI as expected. */ 128 #define MC_DRV_ERR_MCP_ERROR MC_DRV_ERR_DAEMON_UNREACHABLE /**< MobiCore Control Protocol error. See MC_DRV_ERROR_MCP(). */ 129 #define MC_DRV_ERR_INVALID_LENGTH MC_DRV_ERR_NO_FREE_MEMORY /**< Invalid length. */ 130 #define MC_DRV_ERR_KMOD_NOT_OPEN MC_DRV_ERR_NO_FREE_MEMORY /**< Device not open. */ 131 #define MC_DRV_ERR_BUFFER_ALREADY_MAPPED MC_DRV_ERR_BULK_MAPPING /**< Buffer is already mapped to this Trustlet. */ 132 #define MC_DRV_ERR_BLK_BUFF_NOT_FOUND MC_DRV_ERR_BULK_UNMAPPING /**< Unable to find internal handle for buffer. */ 133 134 #define MC_DRV_ERR_DAEMON_DEVICE_NOT_OPEN 0x00000021 /**< No device associated with connection. */ 135 #define MC_DRV_ERR_DAEMON_WSM_HANDLE_NOT_FOUND MC_DRV_ERR_WSM_NOT_FOUND /**< Daemon could not find WSM handle. */ 136 #define MC_DRV_ERR_DAEMON_UNKNOWN_SESSION MC_DRV_ERR_UNKNOWN_SESSION /**< The specified session is unknown to Daemon. */ 137 138 #define MAKE_MC_DRV_MCP_ERROR(mcpCode) (MC_DRV_ERR_MCP_ERROR | ((mcpCode&0x000FFFFF)<<8)) 139 #define MAKE_MC_DRV_KMOD_WITH_ERRNO(theErrno) (MC_DRV_ERR_KERNEL_MODULE| (((theErrno)&0x0000FFFF)<<16)) 140 141 /** 142 * Driver control command. 143 */ 144 typedef enum { 145 MC_CTRL_DUMMY = 1 /**< Dummy. */ 146 } mcDriverCtrl_t; 147 148 149 /** Structure of Session Handle, includes the Session ID and the Device ID the Session belongs to. 150 * The session handle will be used for session-based MobiCore communication. 151 * It will be passed to calls which address a communication end point in the MobiCore environment. 152 */ 153 typedef struct { 154 uint32_t sessionId; /**< MobiCore session ID */ 155 uint32_t deviceId; /**< Device ID the session belongs to */ 156 } mcSessionHandle_t; 157 158 /** Information structure about additional mapped Bulk buffer between the Trustlet Connector (Nwd) and 159 * the Trustlet (Swd). This structure is initialized from a Trustlet Connector by calling mcMap(). 160 * In order to use the memory within a Trustlet the Trustlet Connector has to inform the Trustlet with 161 * the content of this structure via the TCI. 162 */ 163 typedef struct { 164 void *sVirtualAddr; /**< The virtual address of the Bulk buffer regarding the address space of the Trustlet, already includes a possible offset! */ 165 uint32_t sVirtualLen; /**< Length of the mapped Bulk buffer */ 166 } mcBulkMap_t; 167 168 169 #define MC_DEVICE_ID_DEFAULT 0 /**< The default device ID */ 170 #define MC_INFINITE_TIMEOUT ((int32_t)(-1)) /**< Wait infinite for a response of the MC. */ 171 #define MC_NO_TIMEOUT 0 /**< Do not wait for a response of the MC. */ 172 #define MC_MAX_TCI_LEN 0x100000 /**< TCI/DCI must not exceed 1MiB */ 173 174 /* Mark only the following functions for export */ 175 #pragma GCC visibility push(default) 176 177 /** Open a new connection to a MobiCore device. 178 * 179 * mcOpenDevice() initializes all device specific resources required to communicate 180 * with an MobiCore instance located on the specified device in the system. If the device 181 * does not exist the function will return MC_DRV_ERR_UNKNOWN_DEVICE. 182 * 183 * @param [in] deviceId Identifier for the MobiCore device to be used. MC_DEVICE_ID_DEFAULT refers to the default device. 184 * 185 * @return MC_DRV_OK if operation has been successfully completed. 186 * @return MC_DRV_ERR_INVALID_OPERATION if device already opened. 187 * @return MC_DRV_ERR_DAEMON_UNREACHABLE when problems with daemon occur. 188 * @return MC_DRV_ERR_UNKNOWN_DEVICE when deviceId is unknown. 189 * @return MC_DRV_ERR_INVALID_DEVICE_FILE if kernel module under /dev/mobicore cannot be opened 190 * 191 * Uses a Mutex. 192 */ 193 __MC_CLIENT_LIB_API mcResult_t mcOpenDevice( 194 uint32_t deviceId 195 ); 196 197 /** Close the connection to a MobiCore device. 198 * When closing a device, active sessions have to be closed beforehand. 199 * Resources associated with the device will be released. 200 * The device may be opened again after it has been closed. 201 * 202 * @param [in] deviceId Identifier for the MobiCore device. MC_DEVICE_ID_DEFAULT refers to the default device. 203 * 204 * @return MC_DRV_OK if operation has been successfully completed. 205 * @return MC_DRV_ERR_UNKNOWN_DEVICE when device id is invalid. 206 * @return MC_DRV_ERR_SESSION_PENDING when a session is still open. 207 * @return MC_DRV_ERR_DAEMON_UNREACHABLE when problems with daemon occur. 208 * 209 * Uses a Mutex. 210 */ 211 __MC_CLIENT_LIB_API mcResult_t mcCloseDevice( 212 uint32_t deviceId 213 ); 214 215 /** Open a new session to a Trustlet. The trustlet with the given UUID has to be available in the flash filesystem. 216 * 217 * Write MCP open message to buffer and notify MobiCore about the availability of a new command. 218 * Waits till the MobiCore responses with the new session ID (stored in the MCP buffer). 219 * 220 * @param [in,out] session On success, the session data will be returned. Note that session.deviceId has to be the device id of an opened device. 221 * @param [in] uuid UUID of the Trustlet to be opened. 222 * @param [in] tci TCI buffer for communicating with the trustlet. 223 * @param [in] tciLen Length of the TCI buffer. Maximum allowed value is MC_MAX_TCI_LEN. 224 * 225 * @return MC_DRV_OK if operation has been successfully completed. 226 * @return MC_DRV_INVALID_PARAMETER if session parameter is invalid. 227 * @return MC_DRV_ERR_UNKNOWN_DEVICE when device id is invalid. 228 * @return MC_DRV_ERR_DAEMON_UNREACHABLE when problems with daemon socket occur. 229 * @return MC_DRV_ERR_UNKNOWN_DEVICE when daemon returns an error. 230 * 231 * Uses a Mutex. 232 */ 233 __MC_CLIENT_LIB_API mcResult_t mcOpenSession( 234 mcSessionHandle_t *session, 235 const mcUuid_t *uuid, 236 uint8_t *tci, 237 uint32_t tciLen 238 ); 239 240 /** Close a Trustlet session. 241 * 242 * Closes the specified MobiCore session. The call will block until the session has been closed. 243 * 244 * @pre Device deviceId has to be opened in advance. 245 * 246 * @param [in] session Session to be closed. 247 * 248 * @return MC_DRV_OK if operation has been successfully completed. 249 * @return MC_DRV_INVALID_PARAMETER if session parameter is invalid. 250 * @return MC_DRV_ERR_UNKNOWN_SESSION when session id is invalid. 251 * @return MC_DRV_ERR_UNKNOWN_DEVICE when device id of session is invalid. 252 * @return MC_DRV_ERR_DAEMON_UNREACHABLE when problems with daemon occur. 253 * @return MC_DRV_ERR_INVALID_DEVICE_FILE when daemon cannot open trustlet file. 254 * 255 * Uses a Mutex. 256 */ 257 __MC_CLIENT_LIB_API mcResult_t mcCloseSession( 258 mcSessionHandle_t *session 259 ); 260 261 /** Notify a session. 262 * Notifies the session end point about available message data. 263 * If the session parameter is correct, notify will always succeed. 264 * Corresponding errors can only be received by mcWaitNotification(). 265 * @pre A session has to be opened in advance. 266 * 267 * @param session The session to be notified. 268 * 269 * @return MC_DRV_OK if operation has been successfully completed. 270 * @return MC_DRV_INVALID_PARAMETER if session parameter is invalid. 271 * @return MC_DRV_ERR_UNKNOWN_SESSION when session id is invalid. 272 * @return MC_DRV_ERR_UNKNOWN_DEVICE when device id of session is invalid. 273 */ 274 __MC_CLIENT_LIB_API mcResult_t mcNotify( 275 mcSessionHandle_t *session 276 ); 277 278 /** Wait for a notification. 279 * 280 * Wait for a notification issued by the MobiCore for a specific session. 281 * The timeout parameter specifies the number of milliseconds the call will wait for a notification. 282 * If the caller passes 0 as timeout value the call will immediately return. If timeout value is below 0 the call will block 283 * until a notification for the session has been received. 284 * 285 * @attention if timeout is below 0, call will block: 286 * Caller has to trust the other side to send a notification to wake him up again. 287 * 288 * @param [in] session The session the notification should correspond to. 289 * @param [in] timeout Time in milliseconds to wait (MC_NO_TIMEOUT : direct return, > 0 : milliseconds, MC_INFINITE_TIMEOUT : wait infinitely) 290 * 291 * @return MC_DRV_OK if notification is available. 292 * @return MC_DRV_ERR_TIMEOUT if no notification arrived in time. 293 * @return MC_DRV_INFO_NOTIFICATION if a problem with the session was encountered. Get more details with mcGetSessionErrorCode(). 294 * @return MC_DRV_ERR_NOTIFICATION if a problem with the socket occurred. 295 * @return MC_DRV_INVALID_PARAMETER if a parameter is invalid. 296 * @return MC_DRV_ERR_UNKNOWN_SESSION when session id is invalid. 297 * @return MC_DRV_ERR_UNKNOWN_DEVICE when device id of session is invalid. 298 */ 299 __MC_CLIENT_LIB_API mcResult_t mcWaitNotification( 300 mcSessionHandle_t *session, 301 int32_t timeout 302 ); 303 304 /** 305 * Allocate a block of world shared memory (WSM). 306 * The MC driver allocates a contiguous block of memory which can be used as WSM. 307 * This implicates that the allocated memory is aligned according to the alignment parameter. 308 * Always returns a buffer of size WSM_SIZE aligned to 4K. 309 * 310 * @param [in] deviceId The ID of an opened device to retrieve the WSM from. 311 * @param [in] align The alignment (number of pages) of the memory block (e.g. 0x00000001 for 4kb). 312 * @param [in] len Length of the block in bytes. 313 * @param [out] wsm Virtual address of the world shared memory block. 314 * @param [in] wsmFlags Platform specific flags describing the memory to be allocated. 315 * 316 * @attention: align and wsmFlags are currently ignored 317 * 318 * @return MC_DRV_OK if operation has been successfully completed. 319 * @return MC_DRV_INVALID_PARAMETER if a parameter is invalid. 320 * @return MC_DRV_ERR_UNKNOWN_DEVICE when device id is invalid. 321 * @return MC_DRV_ERR_NO_FREE_MEMORY if no more contiguous memory is available in this size or for this process. 322 * 323 * Uses a Mutex. 324 */ 325 __MC_CLIENT_LIB_API mcResult_t mcMallocWsm( 326 uint32_t deviceId, 327 uint32_t align, 328 uint32_t len, 329 uint8_t **wsm, 330 uint32_t wsmFlags 331 ); 332 333 /** 334 * Free a block of world shared memory (WSM). 335 * The MC driver will free a block of world shared memory (WSM) previously allocated with 336 * mcMallocWsm(). The caller has to assure that the address handed over to the driver 337 * is a valid WSM address. 338 * 339 * @param [in] deviceId The ID to which the given address belongs. 340 * @param [in] wsm Address of WSM block to be freed. 341 * 342 * @return MC_DRV_OK if operation has been successfully completed. 343 * @return MC_DRV_INVALID_PARAMETER if a parameter is invalid. 344 * @return MC_DRV_ERR_UNKNOWN_DEVICE when device id is invalid. 345 * @return MC_DRV_ERR_FREE_MEMORY_FAILED on failures. 346 * 347 * Uses a Mutex. 348 */ 349 __MC_CLIENT_LIB_API mcResult_t mcFreeWsm( 350 uint32_t deviceId, 351 uint8_t *wsm 352 ); 353 354 /** 355 * Map additional bulk buffer between a Trustlet Connector (TLC) and the Trustlet (TL) for a session. 356 * Memory allocated in user space of the TLC can be mapped as additional communication channel 357 * (besides TCI) to the Trustlet. Limitation of the Trustlet memory structure apply: only 6 chunks can be mapped 358 * with a maximum chunk size of 1 MiB each. 359 * 360 * @attention It is up to the application layer (TLC) to inform the Trustlet about the additional mapped bulk memory. 361 * 362 * @param [in] session Session handle with information of the deviceId and the sessionId. The 363 * given buffer is mapped to the session specified in the sessionHandle. 364 * @param [in] buf Virtual address of a memory portion (relative to TLC) to be shared with the Trustlet, already includes a possible offset! 365 * @param [in] len length of buffer block in bytes. 366 * @param [out] mapInfo Information structure about the mapped Bulk buffer between the TLC (Nwd) and 367 * the TL (Swd). 368 * 369 * @return MC_DRV_OK if operation has been successfully completed. 370 * @return MC_DRV_INVALID_PARAMETER if a parameter is invalid. 371 * @return MC_DRV_ERR_UNKNOWN_SESSION when session id is invalid. 372 * @return MC_DRV_ERR_UNKNOWN_DEVICE when device id of session is invalid. 373 * @return MC_DRV_ERR_DAEMON_UNREACHABLE when problems with daemon occur. 374 * @return MC_DRV_ERR_BULK_MAPPING when buf is already uses as bulk buffer or when registering the buffer failed. 375 * 376 * Uses a Mutex. 377 */ 378 __MC_CLIENT_LIB_API mcResult_t mcMap( 379 mcSessionHandle_t *session, 380 void *buf, 381 uint32_t len, 382 mcBulkMap_t *mapInfo 383 ); 384 385 /** 386 * Remove additional mapped bulk buffer between Trustlet Connector (TLC) and the Trustlet (TL) for a session. 387 * 388 * @attention The bulk buffer will immediately be unmapped from the session context. 389 * @attention The application layer (TLC) must inform the TL about unmapping of the additional bulk memory before calling mcUnmap! 390 * 391 * @param [in] session Session handle with information of the deviceId and the sessionId. The 392 * given buffer is unmapped from the session specified in the sessionHandle. 393 * @param [in] buf Virtual address of a memory portion (relative to TLC) shared with the TL, already includes a possible offset! 394 * @param [in] mapInfo Information structure about the mapped Bulk buffer between the TLC (Nwd) and 395 * the TL (Swd). 396 * @attention The clientlib currently ignores the len field in mapInfo. 397 * 398 * @return MC_DRV_OK if operation has been successfully completed. 399 * @return MC_DRV_INVALID_PARAMETER if a parameter is invalid. 400 * @return MC_DRV_ERR_UNKNOWN_SESSION when session id is invalid. 401 * @return MC_DRV_ERR_UNKNOWN_DEVICE when device id of session is invalid. 402 * @return MC_DRV_ERR_DAEMON_UNREACHABLE when problems with daemon occur. 403 * @return MC_DRV_ERR_BULK_UNMAPPING when buf was not registered earlier or when unregistering failed. 404 * 405 * Uses a Mutex. 406 */ 407 __MC_CLIENT_LIB_API mcResult_t mcUnmap( 408 mcSessionHandle_t *session, 409 void *buf, 410 mcBulkMap_t *mapInfo 411 ); 412 413 414 /** 415 * @attention: Not implemented. 416 * Execute driver specific command. 417 * mcDriverCtrl() can be used to execute driver specific commands. 418 * Besides the control command MC_CTRL_GET_VERSION commands are implementation specific. 419 * Please refer to the corresponding specification of the driver manufacturer. 420 * 421 * @param [in] param Command ID of the command to be executed. 422 * @param [in, out] data Command data and response depending on command. 423 * @param [in] len Length of the data block. 424 * 425 * @return MC_DRV_ERR_NOT_IMPLEMENTED. 426 */ 427 __MC_CLIENT_LIB_API mcResult_t mcDriverCtrl( 428 mcDriverCtrl_t param, 429 uint8_t *data, 430 uint32_t len 431 ); 432 433 /** 434 * Get additional error information of the last error that occured on a session. 435 * After the request the stored error code will be deleted. 436 * 437 * @param [in] session Session handle with information of the deviceId and the sessionId. 438 * @param [out] lastErr >0 Trustlet has terminated itself with this value, <0 Trustlet is dead because of an error within the MobiCore (e.g. Kernel exception). 439 * See also notificationPayload_t enum in MCI definition at "mcinq.h". 440 * 441 * @return MC_DRV_OK if operation has been successfully completed. 442 * @return MC_DRV_INVALID_PARAMETER if a parameter is invalid. 443 * @return MC_DRV_ERR_UNKNOWN_SESSION when session id is invalid. 444 * @return MC_DRV_ERR_UNKNOWN_DEVICE when device id of session is invalid. 445 */ 446 __MC_CLIENT_LIB_API mcResult_t mcGetSessionErrorCode( 447 mcSessionHandle_t *session, 448 int32_t *lastErr 449 ); 450 451 /** 452 * Get MobiCore version information of a device. 453 * 454 * @param [in] deviceId of an open device. 455 * @param [out] versionInfo MobiCore version info. 456 * 457 * @return MC_DRV_OK if operation has been successfully completed. 458 * @return MC_DRV_ERR_UNKNOWN_DEVICE when device is not open. 459 * @return MC_DRV_INVALID_PARAMETER if a parameter is invalid. 460 * @return MC_DRV_ERR_DAEMON_UNREACHABLE when problems with daemon occur. 461 */ 462 __MC_CLIENT_LIB_API mcResult_t mcGetMobiCoreVersion( 463 uint32_t deviceId, 464 mcVersionInfo_t *versionInfo 465 ); 466 #pragma GCC visibility pop 467 #endif /** MCDRIVER_H_ */ 468 469 /** @} */ 470