1 /** @addtogroup NQ 2 * @{ 3 * Notifications inform the MobiCore runtime environment that information is pending in a WSM buffer. 4 * The Trustlet Connector (TLC) and the corresponding trustlet also utilize this buffer to notify 5 * each other about new data within the Trustlet Connector Interface (TCI). 6 * 7 * The buffer is set up as a queue, which means that more than one notification can be written to the buffer 8 * before the switch to the other world is performed. Each side therefore facilitates an incoming and an 9 * outgoing queue for communication with the other side. 10 * 11 * Notifications hold the session ID, which is used to reference the communication partner in the other world. 12 * So if, e.g., the TLC in the normal world wants to notify his trustlet about new data in the TLC buffer 13 * 14 * @file 15 * Notification queue declarations. 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 NQ_H_ 44 #define NQ_H_ 45 46 /** \name NQ Size Defines 47 * Minimum and maximum count of elements in the notification queue. 48 * @{ */ 49 #define MIN_NQ_ELEM 1 /**< Minimum notification queue elements. */ 50 #define MAX_NQ_ELEM 64 /**< Maximum notification queue elements. */ 51 /** @} */ 52 53 /** \name NQ Length Defines 54 * Minimum and maximum notification queue length. 55 * @{ */ 56 #define MIN_NQ_LEN (MIN_NQ_ELEM * sizeof(notification_t)) /**< Minimum notification length (in bytes). */ 57 #define MAX_NQ_LEN (MAX_NQ_ELEM * sizeof(notification_t)) /**< Maximum notification length (in bytes). */ 58 /** @} */ 59 60 /** \name Session ID Defines 61 * Standard Session IDs. 62 * @{ */ 63 #define SID_MCP 0 /**< MCP session ID is used when directly communicating with the MobiCore (e.g. for starting and stopping of trustlets). */ 64 #define SID_INVALID 0xffffffff /**< Invalid session id is returned in case of an error. */ 65 /** @} */ 66 67 /** Notification data structure. */ 68 typedef struct{ 69 uint32_t sessionId; /**< Session ID. */ 70 int32_t payload; /**< Additional notification information. */ 71 } notification_t; 72 73 /** Notification payload codes. 74 * 0 indicated a plain simple notification, 75 * a positive value is a termination reason from the task, 76 * a negative value is a termination reason from MobiCore. 77 * Possible negative values are given below. 78 */ 79 typedef enum { 80 ERR_INVALID_EXIT_CODE = -1, /**< task terminated, but exit code is invalid */ 81 ERR_SESSION_CLOSE = -2, /**< task terminated due to session end, no exit code available */ 82 ERR_INVALID_OPERATION = -3, /**< task terminated due to invalid operation */ 83 ERR_INVALID_SID = -4, /**< session ID is unknown */ 84 ERR_SID_NOT_ACTIVE = -5 /**< session is not active */ 85 } notificationPayload_t; 86 87 /** Declaration of the notification queue header. 88 * layout as specified in the data structure specification. 89 */ 90 typedef struct { 91 uint32_t writeCnt; /**< Write counter. */ 92 uint32_t readCnt; /**< Read counter. */ 93 uint32_t queueSize; /**< Queue size. */ 94 } notificationQueueHeader_t; 95 96 /** Queue struct which defines a queue object. 97 * The queue struct is accessed by the queue<operation> type of 98 * function. elementCnt must be a power of two and the power needs 99 * to be smaller than power of uint32_t (obviously 32). 100 */ 101 typedef struct { 102 notificationQueueHeader_t hdr; /**< Queue header. */ 103 notification_t notification[MIN_NQ_ELEM]; /**< Notification elements. */ 104 } notificationQueue_t; 105 106 #endif /** NQ_H_ */ 107 108 /** @} */ 109