/* * * Copyright (C) 2012 - 2021, Samsung Electronics Co., Ltd. * * TEE Low Level API */ /** * @file * @brief The Trusted User Interface Low Level API provides instruments * for more flexible management of peripheral in TEE. Low Level TUI API * includes three components: * * Event Queue API - for generic event exchange between TAs and * device drivers * * Peripheral API - for flexible management of peripheral. Each peripheral * can be taken to TEE control or returned to REE control. * * TUI LL API - provides access to device video buffer and allows TA * to draw GUI directly in it. * @copyright (C) 2012 - 2020, Samsung Electronics Co., Ltd. * @addtogroup tui * @{ */ #pragma once #include #include /** @def TEE_CORE_API_EVENT * Event API is available. */ #define TEE_CORE_API_EVENT #if defined(TEE_CORE_API_EVENT) /** @def TEE_TUI_LOW_MAJOR_VERSION * Major version. */ #define TEE_TUI_LOW_MAJOR_VERSION (1) /** @def TEE_TUI_LOW_MINOR_VERSION * Minor version. */ #define TEE_TUI_LOW_MINOR_VERSION (0) /** @def TEE_TUI_LOW_MAINTENANCE_VERSION * Maintenance version. */ #define TEE_TUI_LOW_MAINTENANCE_VERSION (0) /** @def TEE_TUI_LOW_VERSION * TUI low level version. */ #define TEE_TUI_LOW_VERSION (TEE_TUI_LOW_MAJOR_VERSION << 24) + (TEE_TUI_LOW_MINOR_VERSION << 16) + \ (TEE_TUI_LOW_MAINTENANCE_VERSION << 8) /** @def TEE_TUI_LOW_1_0 * Helper value. */ #define TEE_TUI_LOW_1_0 (TEE_TUI_LOW_VERSION) /** @brief Opaque handle for an event queue. */ typedef struct __TEE_EventQueueHandle* TEE_EventQueueHandle; /** @brief Opaque handle for a direct access to a peripheral management. */ typedef struct __TEE_PeripheralHandle* TEE_PeripheralHandle; /** @brief Opaque handle for a specific source of events. */ typedef struct __TEE_EventSourceHandle* TEE_EventSourceHandle; /** @brief Handle for a display. */ struct __TEE_TUIDisplay { uint32_t magic; }; /** @brief Opaque handle for a display. */ typedef struct __TEE_TUIDisplay TEE_TUIDisplay; /** @brief Handle for a surface. */ struct __TEE_TUISurface { uintptr_t hndl; /* surface node address */ }; /** @brief Opaque handle for a surface. */ typedef struct __TEE_TUISurface TEE_TUISurface; /** @def TEE_MAX_EVENT_PAYLOAD_SIZE * Event payload buffer length. */ #define TEE_MAX_EVENT_PAYLOAD_SIZE 32 //bytes /** @def TEE_INVALID_HANDLE * Invalid handle. Is defined in 9.2.1 of Core spec to denote peripheral subsystem invalid handle. * Used in spec to check/denote validiy of TEE_EventQueueHandle and TEE_PeripheralHandle. */ #define TEE_INVALID_HANDLE ((TEE_EventQueueHandle) (0)) /** @def IS_INVALID_HANDLE * Macro to check handle value against TEE_INVALID_HANDLE. */ #define IS_INVALID_HANDLE(_ph_) \ ((void *)(_ph_) == (void *)(TEE_INVALID_HANDLE)) /** @def IS_INVALID_HANDLE_PTR * Macro to check handle pointer against NULL and value against TEE_INVALID_HANDLE. */ #define IS_INVALID_HANDLE_PTR(_pph_) \ ((_pph_) == NULL || IS_INVALID_HANDLE(*_pph_)) /** @brief There is a value indicating the source of an event. */ typedef uint32_t TEE_EVENT_TYPE; /** @brief There is a value used to identify a peripheral attached to the device */ typedef uint32_t TEE_PERIPHERAL_TYPE; /** @brief There is a uint32_t, used as a unique identifier for a peripheral on a given TEE. */ typedef uint32_t TEE_PeripheralId; /** @brief There is an identifier for a peripheral state entry on a given TEE. */ typedef uint32_t TEE_PeripheralStateId; /** @brief A value indicates which of several types has been used to store the * configuration information in a TEE_PeripheralState.tag field. */ typedef uint32_t TEE_PeripheralValueType; /** @brief There is a value indicating the action of a button. */ typedef uint32_t TEE_EVENT_TUI_BUTTON_ACTION; /** @brief There is a value indicating the functionality attributed to a button. */ typedef uint32_t TEE_EVENT_TUI_BUTTON_TYPE; /** @brief There is a value defining the action of a key. */ typedef uint8_t TEE_EVENT_TUI_KEY_ACTION; /** @brief There is a value indicating the event being passed from the REE. */ typedef uint16_t TEE_EVENT_TUI_REE_TYPE; /** @brief There is a value indicating the event being passed from the TEE. */ typedef uint16_t TEE_EVENT_TUI_TEE_TYPE; /** @brief There is a value indicating the event being passed from touch driver. */ typedef uint16_t TEE_EVENT_TUI_TOUCH_ACTION; /** @brief There is a value which sets a color mode for graphic functions. */ typedef uint32_t TEE_TUI_SURFACE_OPACITY; /** @brief There is a value which sets an operation for surface transformation. */ typedef uint32_t TEE_TUI_OPERATION; /** @brief Event type valyes. */ enum { TEE_EVENT_TYPE_ALL = 0x00100000, /**< All events */ TEE_EVENT_TYPE_CORE_CLIENT_CANCEL = 0x00100001, /**< Cancel TUI session */ TEE_EVENT_TYPE_CORE_TIMER = 0x00100002, /**< Timer event */ TEE_EVENT_TYPE_CORE_ACCESS_CHANGE = 0x00100003, /**< Access changed. ******************************************** This event is not devined in GP spec. It must be a mistake. ********************************************/ TEE_EVENT_TYPE_ILLEGAL_VALUE = 0x0010ffff, /**< Illegal value */ TEE_EVENT_TYPE_BIO = 0x00420000, /**< Biometrics API */ TEE_EVENT_TYPE_TUI_ALL = 0x00550000, /**< All TUI events */ TEE_EVENT_TYPE_TUI_BUTTON = 0x00550001, /**< TUI Button event */ TEE_EVENT_TYPE_TUI_KEYBOARD = 0x00550002, /**< TUI Keyboard event */ TEE_EVENT_TYPE_TUI_REE = 0x00550003, /**< TUI REE event */ TEE_EVENT_TYPE_TUI_TOUCH = 0x00550004, /**< TUI Touch event */ }; /** @brief Peripheral type values. */ enum { TEE_PERIPHERAL_OS = 0x00000001, /**< OS */ TEE_PERIPHERAL_CAMERA = 0x00000002, /**< Camera */ TEE_PERIPHERAL_MICROPHONE = 0x00000003, /**< Microphone */ TEE_PERIPHERAL_ACCELEROMETER = 0x00000004, /**< Accelerometer */ TEE_PERIPHERAL_NFC = 0x00000005, /**< NFC */ TEE_PERIPHERAL_BLUETOOTH = 0x00000006, /**< Bluetooth */ TEE_PERIPHERAL_USB = 0x00000007, /**< USB */ TEE_PERIPHERAL_FINGERPRINT = 0x00000008, /**< Fingerprint */ TEE_PERIPHERAL_KEYBOARD = 0x00000009, /**< Keyboard */ TEE_PERIPHERAL_TOUCH = 0x0000000A, /**< Touch */ TEE_PERIPHERAL_BIO = 0x0000000B, /**< Biometrics API */ TEE_PERIPHERAL_ILLEGAL_VALUE = INT_MAX, /**< Illegal value */ }; /** @brief Peripheral flag values. */ enum { TEE_PERIPHERAL_FLAG_REE_CONTROLLED = 0x00000000, /**< TEE does not control this peripheral. */ TEE_PERIPHERAL_FLAG_TEE_CONTROLLABLE = 0x00000001, /**< TEE does controls this peripheral. */ TEE_PERIPHERAL_FLAG_EVENT_SOURCE = 0x00000002, /**< TEE can parse the events generated by this peripheral. */ TEE_PERIPHERAL_FLAG_LOCKED = 0x00000004, /**< This peripheral has been locked for access by a TA or the REE. */ TEE_PERIPHERAL_FLAG_OWNED = 0x00000008, /**< This peripheral has been locked for access by this TA instance. */ }; /** @brief TEE_PeripheralStateId values. */ enum { TEE_PERIPHERAL_STATE_NAME = 0x00000001, /**< string, Name */ TEE_PERIPHERAL_STATE_FW_INFO = 0x00000002, /**< string, FW version */ TEE_PERIPHERAL_STATE_MANUFACTURER = 0x00000003, /**< string, Manufacturer info */ TEE_PERIPHERAL_STATE_FLAGS = 0x00000004, /**< uint32, Flags */ TEE_PERIPHERAL_STATE_EXCLUSIVE_ACCESS = 0x00000005, /**< bool, Exclusive access */ TEE_PERIPHERAL_STATE_ILLEGAL_VALUE = INT_MAX, /**< Illegal value */ }; /** @brief TEE_PeripheralValueType values. */ enum { TEE_PERIPHERAL_VALUE_UINT64 = 0x00000000, /**< uint64 */ TEE_PERIPHERAL_VALUE_UINT32 = 0x00000001, /**< uint32 */ TEE_PERIPHERAL_VALUE_UINT16 = 0x00000002, /**< uint16 */ TEE_PERIPHERAL_VALUE_UINT8 = 0x00000003, /**< uint8 */ TEE_PERIPHERAL_VALUE_BOOL = 0x00000004, /**< bool */ TEE_PERIPHERAL_VALUE_STRING = 0x00000005, /**< string */ TEE_PERIPHERAL_VALUE_ILLEGAL_VALUE = INT_MAX, /**< Illegal value */ }; /** @brief TEE_EVENT_TUI_BUTTON_ACTION values. */ enum { TEE_EVENT_TUI_BUTTON_UP = 0x00000000, /**< Up */ TEE_EVENT_TUI_BUTTON_DOWN = 0x00000001, /**< Down */ TEE_EVENT_TUI_BUTTON_ACTION_ILLEGAL_VALUE = INT_MAX, /**< Illegal value */ }; /** @brief TEE_EVENT_TUI_BUTTON_TYPE values. */ enum { TEE_EVENT_TUI_BUTTON_BACK = 0x00000000, /**< Back */ TEE_EVENT_TUI_BUTTON_HOME = 0x00000001, /**< Home */ TEE_EVENT_TUI_BUTTON_MENU = 0x00000002, /**< Menu */ TEE_EVENT_TUI_BUTTON_POWER = 0x00000003, /**< Power */ TEE_EVENT_TUI_BUTTON_VOLUMEDOWN = 0x00000004, /**< Volume down */ TEE_EVENT_TUI_BUTTON_VOLUMEUP = 0x00000005, /**< Volume up */ TEE_EVENT_TUI_BUTTON_TYPE_ILLEGAL_VALUE = INT_MAX, /**< Illegal value */ }; /** @brief TEE_EVENT_TUI_KEY_ACTION values. */ enum { TEE_EVENT_TUI_KEY_ACTION_UP = 0x00, /**< Up */ TEE_EVENT_TUI_KEY_ACTION_DOWN = 0x01, /**< Down */ TEE_EVENT_TUI_KEY_ACTION_ILLEGAL_VALUE = 0x7f, /**< Illegal value */ }; /** @brief TEE_EVENT_TUI_REE_TYPE values. */ enum { TEE_EVENT_TUI_REE_DISPLAYSTOPPED = 0x0000, /**< Return control to REE */ TEE_EVENT_TUI_REE_CANCEL = 0x0001, /**< Power event */ TEE_EVENT_TUI_REE_ROT90 = 0x0002, /**< Rotation 90 */ TEE_EVENT_TUI_REE_ROT180 = 0x0003, /**< Rotation 180 */ TEE_EVENT_TUI_REE_ROT270 = 0x0004, /**< Rotation 270 */ TEE_EVENT_TUI_REE_ILLEGAL_VALUE = 0x7fff, /**< Illegal value */ }; /** @brief TEE_EVENT_TUI_TEE_TYPE values. */ enum { TEE_EVENT_TUI_TEE_DISPLAYSTOPPED = 0x0000, /**< Return control to REE */ TEE_EVENT_TUI_TEE_CANCEL = 0x0001, /**< Power event */ TEE_EVENT_TUI_TEE_ROT90 = 0x0002, /**< Rotation 90 */ TEE_EVENT_TUI_TEE_ROT180 = 0x0003, /**< Rotation 180 */ TEE_EVENT_TUI_TEE_ROT270 = 0x0004, /**< Rotation 270 */ TEE_EVENT_TUI_TEE_ILLEGAL_VALUE = 0x7fff, /**< Illegal value */ }; /** @brief TEE_EVENT_TUI_TOUCH_ACTION values. */ enum { TEE_EVENT_TUI_TOUCH_ACTION_DOWN = 0x0000, /**< Down */ TEE_EVENT_TUI_TOUCH_ACTION_MOVE = 0x0001, /**< Move */ TEE_EVENT_TUI_TOUCH_ACTION_UP = 0x0002, /**< Up */ TEE_EVENT_TUI_TOUCH_ACTION_ILLEGAL_VALUE = 0x7fff, /**< Illegal value */ }; /** @brief TEE_TUI_DISPLAY_INFO_FLAGS values. */ enum { TEE_TUI_DISPLAY_INFO_FLAG_NONESET = 0x00000000, /**< No flags set. */ TEE_TUI_DISPLAY_INFO_FLAG_HASTOUCH = 0x00000001, /**< TEE can return secure touch events generated by this display. */ TEE_TUI_DISPLAY_INFO_FLAG_HASPRESSURE = 0x00000002, /**< Display returns pressure information about touches. */ TEE_TUI_DISPLAY_INFO_FLAG_CANDEBOUNCE = 0x00000004, /**< TEE can attempt to debounce touch events from this display. */ TEE_TUI_DISPLAY_INFO_FLAG_MULTITOUCH = 0x00000008, /**< Display can generate touch events for multiple fingers */ }; /** @brief TEE_TUI_INIT_SESSION_LOW_FLAGS values. */ enum { TEE_TUI_INIT_SESSION_LOW_FLAG_NONESET = 0x00000000, /**< No flags set. */ TEE_TUI_INIT_SESSION_LOW_FLAG_REQUIREINDICATOR = 0x00000001, /**< The TA requires the TEE to set the security indicator. */ }; /** @brief TEE_TUI_OPERATION values. */ enum { TEE_TUI_OPERATION_NULL = 0x00000000, /**< No transformation */ TEE_TUI_OPERATION_ROTATE90 = 0x00000001, /**< Rotate the image 90 degrees clockwise */ TEE_TUI_OPERATION_ROTATE180 = 0x00000002, /**< Rotate the image 180 degrees */ TEE_TUI_OPERATION_ROTATE270 = 0x00000003, /**< Rotate the image 270 degrees clockwise */ TEE_TUI_OPERATION_FLIPH = 0x00000004, /**< Flip the image about its horizontal axis */ TEE_TUI_OPERATION_FLIPV = 0x00000008, /**< Flip the image about its vertical axis */ TEE_TUI_OPERATION_INVERTRED = 0x00000010, /**< Invert the value of the Red color values */ TEE_TUI_OPERATION_INVERTGREEN = 0x00000020, /**< Invert the value of the Green color values */ TEE_TUI_OPERATION_INVERTBLUE = 0x00000040, /**< Invert the value of the Blue color values */ TEE_TUI_OPERATION_INVERTALPHA = 0x00000080, /**< Invert the value of the Alpha channel */ TEE_TUI_OPERATION_ILLEGAL_VALUE = 0x80000000, /**< Illegal value */ }; /** @brief TEE_TUI_SURFACE_OPACITY values. */ enum { TEE_TUI_SURFACE_OPACITY_OPAQUE = 0x00000001, /**< target.RGBA = source.RGBA */ TEE_TUI_SURFACE_OPACITY_SOURCEALPHA = 0x00000002, /**< target.RGB = source.RGB * source.Alpha */ TEE_TUI_SURFACE_OPACITY_TARGETALPHA = 0x00000003, /**< target.RGB = source.RGB * target.Alpha */ TEE_TUI_SURFACE_OPACITY_TRANSPARENT = 0x00000004, /**< target.RGBA = target.RGBA + source.RGBA */ TEE_TUI_SURFACE_OPACITY_BLENDSOURCE = 0x00000005, /**< target.RGBA = target.RGBA * source.Alpha + source.RGBA */ TEE_TUI_SURFACE_OPACITY_BLENDTARGET = 0x00000006, /**< target.RGBA = target.RGBA + source.RGBA * target.Alpha */ TEE_TUI_SURFACE_OPACITY_BLEND = 0x00000007, /**< target.RGBA = target.RGBA * source.Alpha + source.RGBA * target.Alpha */ TEE_TUI_SURFACE_OPACITY_ILLEGAL_VALUE = INT_MAX, /**< Illegal value */ TEES_TUI_SURFACE_OPACITY_BLENDSIMPLE = 0x80000000, /**< Custom simple Opacity mode * target.RGB = (source.RGB * source.A + target.RGB * (0xFF - source.A)) / 0xFF * target.A = target.A * (use simple mathematical arithmetic operations for each color component) */ }; /** * @brief There is a V1 of TEE_Peripheral payload. */ typedef struct { TEE_PERIPHERAL_TYPE periphType; /**< The type of the peripheral. */ TEE_PeripheralId id; /**< A unique identifier for a given peripheral on a TEE. */ } TEE_Peripheral_V1; /** * @brief Structure that is used to provide information about a single peripheral to a TA. */ typedef struct { uint32_t version; /**< The version of the structure – currently always 1. */ union { TEE_Peripheral_V1 v1; } u; } TEE_Peripheral; /** * @brief There is a V1 of TEE_PeripheralDescriptor payload. */ typedef struct { TEE_PeripheralId id; /**< A unique identifier for the peripheral */ TEE_PeripheralHandle peripheralHandle; /**< peripheralHandle enables an owning TA to perform API */ TEE_EventSourceHandle eventSourceHandle; /**< eventSourceHandle can be used to attach peripheral events to an event queue. */ } TEE_PeripheralDescriptor_V1; /** * @brief Structure collects the information required to access a peripheral. */ typedef struct { uint32_t version; /**< The version of the structure – currently always 1. */ union { TEE_PeripheralDescriptor_V1 v1; } u; } TEE_PeripheralDescriptor; /** * @brief Structure contains the current value of a state value */ typedef struct { uint32_t version; /**< The version of the structure – currently always 1. */ TEE_PeripheralValueType tag; /**< State value type. */ TEE_PeripheralStateId id; /**< A unique identifier for the peripheral */ bool ro; /**< read only if true */ union { uint64_t uint64Val; uint32_t uint32Val; uint16_t uint16Val; uint8_t uint8Val; bool boolVal; const char* stringVal; } u; /**< There is a field for different type values */ } TEE_PeripheralState; /** * @brief There is a V1 of TEE_Event payload. */ typedef struct { TEE_EVENT_TYPE eventType; /**< A value identifying the type of event. */ uint64_t timestamp; /**< The time the event occurred given as milliseconds since the TEE was started. */ TEE_EventSourceHandle eventSourceHandle; /**< The handle of the specific event source that created this event. */ uint8_t payload[TEE_MAX_EVENT_PAYLOAD_SIZE]; /**< The content of payload */ } TEE_Event_V1; /** * @brief Structure contains events in the event loop. */ typedef struct { uint32_t version; /**< The version of the structure – currently always 1. */ union { TEE_Event_V1 v1; } u; } TEE_Event; /** * @brief Structure contains a payload of event which is generated * if the accessibility of a peripheral to this TA changes. */ typedef struct { uint32_t version; /**< The version of the structure – currently always 1. */ TEE_PeripheralId id; /**< The TEE_PeripheralId for the peripheral generated the event. */ uint32_t flags; /**< The new state of TEE_PERIPHERAL_STATE_FLAGS. */ } TEE_Event_AccessChange; /** * @brief Structure contains a payload of TEE_EVENT_TYPE_CORE_CLIENT_CANCEL event. */ typedef struct { uint32_t version; /**< The version of the structure – currently always 1. */ } TEE_Event_ClientCancel; /** * @brief Structure contains a payload of TEE_EVENT_TYPE_CORE_CLIENT_TIMER event. */ typedef struct { uint8_t payload[TEE_MAX_EVENT_PAYLOAD_SIZE]; /**< Contents are defined by the TA when the timer is created */ } TEE_Event_Timer; /** * @brief There is a V1 of TEE_Event_TUI_Button payload. */ typedef struct { TEE_EVENT_TUI_BUTTON_ACTION action; /**< Whether the button is pressed or released; */ TEE_EVENT_TUI_BUTTON_TYPE button; /**< The button that generated the event; */ } TEE_Event_TUI_Button_V1; /** * @brief Structure contains a payload of TEE_Event_TUI_Button event. */ typedef struct { uint32_t version; /**< The version of the structure – currently always 1. */ union { TEE_Event_TUI_Button_V1 v1; } u; } TEE_Event_TUI_Button; /** * @brief There is a V1 of TEE_Event_TUI_Keyboard payload. */ typedef struct { TEE_EVENT_TUI_KEY_ACTION action; /**< The action performed, Key Down or Key Up. */ uint32_t mod; /**< The modifier key bitmap as given in the USB HID device class definition [USB HID]. */ uint32_t key; /**< The key identified with the values given in the USB HID Keyboard/Keypad page [USB Key]. */ } TEE_Event_TUI_Keyboard_V1; /** * @brief Structure contains a payload of TEE_Event_TUI_Keyboard event. */ typedef struct { uint32_t version; /**< The version of the structure – currently always 1. */ union { TEE_Event_TUI_Keyboard_V1 v1; } u; } TEE_Event_TUI_Keyboard; /** * @brief There is a V1 of TEE_Event_TUI_REE payload. */ typedef struct { TEE_EVENT_TUI_REE_TYPE event; /**< The event generated by the REE. */ } TEE_Event_TUI_REE_V1; /** * @brief TEE_Event_TUI_REE events enable the REE to pass events to the calling TA. */ typedef struct { uint32_t version; /**< The version of the structure – currently always 1. */ union { TEE_Event_TUI_REE_V1 v1; } u; } TEE_Event_TUI_REE; /** * @brief There is a V1 of TEE_Event_TUI_TEE payload. */ typedef struct { TEE_EVENT_TUI_TEE_TYPE event; /**< The event generated by the TEE.. */ } TEE_Event_TUI_TEE_V1; /** * @brief TEE_Event_TUI_TEE events enable the TEE to pass events to the calling TA. */ typedef struct { uint32_t version; /**< The version of the structure – currently always 1. */ union { TEE_Event_TUI_TEE_V1 v1; } u; } TEE_Event_TUI_TEE; /** * @brief There is a V1 of TEE_Event_TUI_Touch payload. */ typedef struct { uint32_t display; /**< A pointer to the display that was touched. */ TEE_EVENT_TUI_TOUCH_ACTION action; /**< The action performed, Up, Move, Down; */ uint32_t finger; /**< ‘finger’ identifier to allow tracking of multiple touches simultaneously. */ uint32_t pressure; /**< Touch events have an optional ‘pressure’ indication. */ uint32_t x; /**< The coordinates of the touch in pixels, with 0,0 as the top left of the display. */ uint32_t y; } TEE_Event_TUI_Touch_V1; /** * @brief TEE_Event_TUI_Touch events are produced by user interaction with a touch screen display. */ typedef struct { uint32_t version; /**< The version of the structure – currently always 1. */ union { TEE_Event_TUI_Touch_V1 v1; } u; } TEE_Event_TUI_Touch; /** * @brief There is a V1 of TEE_TUIDisplayInfo payload. */ typedef struct { uint32_t bitDepth; /**< The number of bits per pixel. */ uint32_t flags; /**< One or more TEE_TUI_DISPLAY_INFO_FLAGS XORed together; */ uint32_t pixelWidth; /**< The number of pixels in a row across the display. */ uint32_t pixelHeight; /**< The number of rows of pixels in the display. */ uint32_t physicalWidth; /**< The nominal width of the display in millimeters – or zero if unknown. */ uint32_t physicalHeight; /**< The nominal height of the display in millimeters – or zero if unknown. */ uint32_t numPeripherals; /**< The number of associated peripherals. */ TEE_PeripheralId *associatedPeripherals; /**< An array of the peripheral IDs physically associated with this display. */ } TEE_TUIDisplayInfo_V1; /** * @brief The TEE_TUIDisplayInfo structure contains information about a physical display. * It is returned by TEE_TUI_GetDisplayInformation. */ typedef struct { uint32_t version; /**< The version of the structure – currently always 1. */ union { TEE_TUIDisplayInfo_V1 v1; } u; } TEE_TUIDisplayInfo; #ifndef TUI_H_ /** @brief There is a value indicating an image source in TEE_TUIImage structure. */ typedef uint32_t TEE_TUIImageSource; /** @brief TEE_TUIImageSource values. */ enum { TEE_TUI_NO_SOURCE = 0x00000000, /**< No image is provided as input. */ TEE_TUI_REF_SOURCE = 0x00000001, /**< The image source is provided as a memory reference. */ TEE_TUI_OBJECT_SOURCE = 0x00000002, /**< The image source is provided as a Data Object in the Trusted Storage. */ TEE_TUI_IMAGE_ILLEGAL_VALUE = INT_MAX, /**< Illegal value */ }; /** * @brief The TEE_TUIImage structure defines a way to handle an image for label area and buttons. * An image source can be a buffer or a Data Object in the Trusted Storage. */ typedef struct { TEE_TUIImageSource source; /**< The source of the image. */ union { struct { void *image; /**< A buffer containing the image. */ size_t imageLength; } ref; struct { uint32_t storageID; /**< The storage to use. It SHALL be TEE_STORAGE_PRIVATE */ void *objectID; /**< The Object Identifier which refers to a Data Object containing the image in PNG format. */ size_t objectIDLen; } object; }; uint32_t width; /**< The number of pixels of the width of the image. */ uint32_t height; /**< The number of pixels of the height of the image. */ } TEE_TUIImage; #endif /* TUI_H_ */ /** * @brief There is a V1 of TEE_TUISurfaceBuffer payload. */ typedef struct { uint32_t *buf; /**< An array of 32-bit words containing pixel values. */ } TEE_TUISurfaceBuffer_V1; /** * @brief The TEE_TUISurfaceBuffer structure is used to provide a staging area * in which images can be prepared before being sent to a display. */ typedef struct { uint32_t version; /**< The version of the structure – currently always 1.. */ union { TEE_TUISurfaceBuffer_V1 v1; } u; } TEE_TUISurfaceBuffer; /** * @brief There is a V1 of TEE_TUISurfaceInfo payload. */ typedef struct { uint32_t bitDepth; /**< The bit depth supported by this surface. */ uint32_t width; /**< The width of the surface in pixels. */ uint32_t height; /**< The height of the surface in pixels. */ uint32_t stride; /**< The distance in pixels between the start of one row and the start of the next. */ } TEE_TUISurfaceInfo_V1; /** * @brief The TEE_TUISurfaceInfo structure provides information about a surface. */ typedef struct { uint32_t version; /**< The version of the structure – currently always 1. */ union { TEE_TUISurfaceInfo_V1 v1; } u; } TEE_TUISurfaceInfo; /*************************************************************** * Peripheral API Functions * **************************************************************/ /** * The TEE_Peripheral_Close function is used by a TA to release a single peripheral. * Panic Reasons: TEE_Peripheral_Close SHALL NOT panic. * @param[in,out] peripheralDescriptor: A pointer to a TEE_PeripheralDescriptor structure. * * @return TEE_SUCCESS: In case of success. At least one of peripheralHandle and * eventSourceHandle points to a valid handle. * TEE_ERROR_BAD_STATE: The calling TA does not have a valid open handle to the peripheral. * TEE_ERROR_BAD_PARAMETERS: peripheral is NULL. */ TEE_Result TA_EXPORT TEE_Peripheral_Close(TEE_PeripheralDescriptor *peripheralDescriptor); /** * TEE_Peripheral_CloseMultiple is a convenience function which closes all the peripherals * identified in the buffer pointed to by peripherals. * Panic Reasons: TEE_Peripheral_CloseMultiple SHALL NOT panic. * @param[in] numPeripherals: The number of entries in the TEE_PeripheralDescriptor buffer pointed * to by peripherals. * @param[in,out] peripheralDescriptors: A pointer to a buffer of numPeripherals instances of TEE_PeripheralDescriptor. * @return TEE_SUCCESS: In case of success, which is defined as all the requested TEE_PeripheralDescriptor instances * having been successfully closed. * TEE_ERROR_BAD_STATE: The calling TA does not have a valid open handle to at least one of the peripherals. * TEE_ERROR_BAD_PARAMETERS: peripherals is NULL and/or numPeripherals is 0. */ TEE_Result TA_EXPORT TEE_Peripheral_CloseMultiple( const uint32_t numPeripherals, _INOUT_ TEE_PeripheralDescriptor *peripheralDescriptors); /** * The TEE_Peripheral_GetPeripherals function returns information about the peripherals known to the TEE. * Panic Reasons: * + If version is NULL. * + If peripherals is NULL and/or *size is not zero. * + See section 3.4.4 for reasons for [outbuf] generated panic. * + If the Implementation detects any error associated with the execution of this function which is not explicitly * associated with a defined return code for this function. * @param[in,out] version: On entry, the highest version of the TEE_Peripheral structure understood by the calling program. * On return, the actual version returned, which may be lower than the value requested. * @param[out] peripherals: A pointer to an array of TEE_Peripheral structures. This will be populated with information * about the available sources on return. Each structure in the array returns information about one * peripheral. * @param[in,out] size: On entry, the size of peripherals in bytes. * On return, the actual size of the buffer containing the TEE_Peripheral structures in bytes. * @return TEE_SUCCESS: In case of success. * TEE_ERROR_OLD_VERSION: If the version of the TEE_Peripheral structure requested is not supported. * TEE_ERROR_OUT_OF_MEMORY: If the system ran out of resources. * TEE_ERROR_SHORT_BUFFER: If the output buffer is not large enough to hold all the sources. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event which occurred in the * REE while the function was in progress. */ TEE_Result TA_EXPORT TEE_Peripheral_GetPeripherals( _INOUT_ uint32_t *version, _OUTBUF_ TEE_Peripheral *peripherals, size_t *size); /** * The TEE_Peripheral_GetState function enables a TA which knows the state ID of a peripheral state item * to fetch the value of this directly. * Panic Reasons: TEE_Peripheral_GetState SHALL NOT panic. * @param[in] id: The unique peripheral identifier for the peripheral in which we are interested. * @param[in] stateId: The identifier for the state item for which the value is requested. * @param[out] periphType: On return, contains a value of TEE_PeripheralValueType which determines how the * data pointed to by value should be interpreted. * @param[out] value: On return, points to the value of the requested state item. * @return TEE_SUCCESS: State information has been fetched. * TEE_ERROR_BAD_PARAMETERS: The value of one or both of id or stateId are not valid for this TA; * periphType or value is NULL. */ TEE_Result TA_EXPORT TEE_Peripheral_GetState( const TEE_PeripheralId id, const TEE_PeripheralStateId stateId, _OUT_ TEE_PeripheralValueType *periphType, _OUT_ void *value); /** * The TEE_Peripheral_GetStateTable function fetches a buffer containing zero or more instances of TEE_PeripheralState. * Panic Reasons: * + See section 3.4.4 for reasons for [outbuf] generated panic. * + If the Implementation detects any error associated with the execution of this function which is not explicitly * associated with a defined return code for this function. * @param[in] id: The TEE_PeripheralId for the peripheral from which the TA wishes to read data * @param[out] stateTable: A buffer of at least bufSize bytes that on successful return is overwritten with an array of * TEE_PeripheralState structures. * @param[in,out] bufSize: On entry, the size of stateTable in bytes. * On return, the actual number of bytes in the array. * @return TEE_SUCCESS: Data has been written to the peripheral. * TEE_ERROR_BAD_PARAMETERS: The value of id or stateTable is NULL and/or bufSize is 0. */ TEE_Result TA_EXPORT TEE_Peripheral_GetStateTable( _IN_ TEE_PeripheralId id, _OUTBUF_ TEE_PeripheralState *stateTable, size_t *bufSize); /** * The TEE_Peripheral_Open function is used by a TA to obtain descriptor(s) enabling access to a single peripheral. * Panic Reasons: * + If peripheral->id is not known to the system. * + If peripheral->id is already owned by the calling TA instance. * + If the Implementation detects any error associated with the execution of this function which is not explicitly * associated with a defined return code for this function. * @param[in,out] peripheralDescriptor: A pointer to a TEE_PeripheralDescriptor structure. The fields of the structure * pointed to are used as follows: * id: This is the unique identifier for a specific peripheral, as returned by * TEE_Peripheral_GetPeripherals. * peripheralHandle: On entry, the value is ignored and will be overwritten. * On return, the value is set as follows: * TEE_INVALID_HANDLE: This peripheral does not support the Peripheral API. * Other value: An opaque handle which can be used with the Peripheral API functions. * eventSourceHandle: On entry, the value is ignored and will be overwritten. On return, * the value is set as follows: * TEE_INVALID_HANDLE: This peripheral does not support the Event API. * Other value: An opaque handle which can be used with the Event API functions. * @return TEE_SUCCESS: In case of success. At least one of peripheralHandle and eventSourceHandle points to a valid handle. * TEE_ERROR_BAD_PARAMETERS: peripheral is NULL. * TEE_ERROR_ACCESS_DENIED: If the system was unable to acquire exclusive access to a peripheral for which * TEE_PERIPHERAL_STATE_EXCLUSIVE_ACCESS indicates exclusive access is possible. */ TEE_Result TA_EXPORT TEE_Peripheral_Open(_INOUT_ TEE_PeripheralDescriptor *peripheralDescriptor); /** * The TEE_Peripheral_OpenMultiple function is used by a TA to atomically obtain access to multiple peripherals. * Panic Reasons: * + If peripheralDescriptors[x].id for any instance, x, of TEE_PeripheralDescriptor is not known to the system. * + If peripheralDescriptors[x].id for any instance, x, of TEE_PeripheralDescriptor is already owned by the calling TA. * + If the Implementation detects any error associated with the execution of this function which is not explicitly * associated with a defined return code for this function. * @param[in] numPeripherals: The number of entries in the TEE_PeripheralDescriptor buffer pointed to by peripherals. * @param[in,out] peripheralDescriptors: A pointer to a buffer of numPeripherals instances of TEE_PeripheralDescriptor. * @return TEE_SUCCESS: In case of success. At least one of peripheralHandle and eventSourceHandle points to a valid * handle in every entry in peripherals. * TEE_ERROR_BAD_PARAMETERS: peripherals is NULL and/or numPeripherals is 0. * TEE_ERROR_ACCESS_DENIED: If the system was unable to acquire exclusive access to all the requested peripherals. */ TEE_Result TA_EXPORT TEE_Peripheral_OpenMultiple( const uint32_t numPeripherals, _INOUT_ TEE_PeripheralDescriptor *peripheralDescriptors); /** * The TEE_Peripheral_Read function provides a low-level API to read data from the peripheral denoted by peripheralHandle. * Panic Reasons: * + If the calling TA does not provide a valid peripheralHandle. * + See section 3.4.4 for reasons for [outbuf] generated panic. * + If the Implementation detects any error associated with the execution of this function which is not explicitly * associated with a defined return code for this function. * @param[in] peripheralHandle: A valid TEE_PeripheralHandle for the peripheral from which the TA wishes to read data. * @param[out] buf: A buffer of at least bufSize bytes which, on successful return, will be overwritten with data * read back from the peripheral. * @param[in,out] bufSize: On entry, the size of buf in bytes. * On return, the actual number of bytes read from the peripheral. * @return TEE_SUCCESS: Data has been read from the peripheral. The value of bufSize indicates the number of bytes read. * TEE_ERROR_SHORT_BUFFER: If the output buffer is not large enough to hold all the sources. * TEE_ERROR_EXCESS_DATA: Data was read successfully, but the peripheral has more data available to read. * In this case, bufSize is the same value as was indicated when the function was called. It is * recommended that the TA read back the remaining data from the peripheral before continuing. * TEE_ERROR_BAD_PARAMETERS: The value of peripheralHandle is TEE_INVALID_HANDLE; or buf is NULL and bufSize * is not zero. */ TEE_Result TA_EXPORT TEE_Peripheral_Read( _IN_ TEE_PeripheralHandle peripheralHandle, _OUTBUF_ void *buf, size_t *bufSize); /** * The TEE_Peripheral_SetState function enables a TA to set the value of a writeable peripheral state item. * Panic Reasons: TEE_Peripheral_SetState SHALL NOT panic. * @param[in] handle: A valid open handle for the peripheral whose state is to be updated. * @param[in] stateId: The identifier for the state item for which the value is requested. * @param[in] periphType: A value of TEE_PeripheralValueType which determines how the data * pointed to by value should be interpreted. * @param[in] value: The address of the value to be written to the state item. * @return TEE_SUCCESS: State information has been updated. * TEE_ERROR_BAD_PARAMETERS: The value of one or both of handle or stateId are not valid for this TA; * or periphType is not a value defined in TEE_PeripheralValueType; or value is NULL; * or the value which is being written is read-only. */ TEE_Result TA_EXPORT TEE_Peripheral_SetState( const TEE_PeripheralHandle handle, const TEE_PeripheralStateId stateId, const TEE_PeripheralValueType periphType, const void *value); /** * The TEE_Peripheral_Write function provides a low-level API to write data to the peripheral denoted by peripheralHandle. * Panic Reasons: * + If peripheralHandle is not a valid open handle to a peripheral. * + If the Implementation detects any error associated with the execution of this function which is not explicitly * associated with a defined return code for this function. * @param[in] peripheralHandle: A valid TEE_PeripheralHandle for the peripheral from which the TA wishes to read data. * @param[in] buf: A buffer of at least bufSize bytes containing data which has, on successful return, been written * to the peripheral. * @param[in] bufSize: The size of buf in bytes. * @return TEE_SUCCESS: Data has been written to the peripheral. * TEE_ERROR_BAD_PARAMETERS: buf is NULL and/or bufSize is 0. */ TEE_Result TA_EXPORT TEE_Peripheral_Write( _IN_ TEE_PeripheralHandle peripheralHandle, _INBUF_ void *buf, size_t bufSize); /*************************************************************** * Event API Functions * **************************************************************/ /** * The TEE_Event_AddSources function atomically adds new event sources to an existing queue acquired by a call to * TEE_Event_OpenQueue. * Panic Reasons: * + If handle is invalid. * + If the sources array does not contain numSources elements. * + If any pointer in sources is NULL. * + If the Implementation detects any error associated with the execution of this function which is not explicitly * associated with a defined return code for this function. * @param[in] numSources: Defines how many sources are provided. * @param[in] sources: An array of TEE_EventSourceHandle that the TA wants to add to the queue. * @param[in] handle: The handle for the queue. * @return TEE_SUCCESS: In case of success. * TEE_ERROR_BAD_STATE: If the handle does not represent a currently open queue. * TEE_ERROR_BUSY: If any requested resource cannot be reserved. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event which occurred in * the REE while the function was in progress. * TEE_ERROR_OUT_OF_MEMORY: If the system ran out of resources. */ TEE_Result TA_EXPORT TEE_Event_AddSources( uint32_t numSources, _IN_ TEE_EventSourceHandle *sources, _IN_ TEE_EventQueueHandle *handle); /** * The TEE_Event_CancelSources function drops all existing events from a set of sources from a queue previously acquired * by a call to TEE_Event_OpenQueue. * Panic Reasons: * + If handle is invalid. * + If the sources array does not contain numSources elements. * + If any pointer in sources is NULL. * + If the Implementation detects any error associated with the execution of this function which is not explicitly * associated with a defined return code for this function. * @param[in] numSources: Defines how many sources are provided. * @param[in] sources: An array of TEE_EventSourceHandle. Events from these sources are cleared from the queue. * @param[in] handle: The handle for the queue. * @return TEE_SUCCESS: In case of success. * TEE_ERROR_OUT_OF_MEMORY: If the system ran out of resources. * TEE_ERROR_BAD_STATE: If the handle does not represent a currently open queue. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event which occurred in the * REE while the function was in progress. */ TEE_Result TA_EXPORT TEE_Event_CancelSources( uint32_t numSources, _IN_ TEE_EventSourceHandle *sources, _IN_ TEE_EventQueueHandle *handle); /** * The TEE_Event_CloseQueue function releases TUI resources previously acquired by a call to TEE_Event_OpenQueue. * Panic Reasons: * + If handle is invalid. * + If the Implementation detects any error associated with the execution of this function which is not explicitly * associated with a defined return code for this function. * @param[in] handle: The handle to the TEE_EventQueueHandle to close. * @return TEE_SUCCESS: In case of success. * TEE_ERROR_BAD_STATE: If the handle does not represent a currently open queue. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event which occurred in * the REE while the function was in progress. */ TEE_Result TA_EXPORT TEE_Event_CloseQueue(_IN_ TEE_EventQueueHandle *handle); /** * The TEE_Event_DropSources function removes one or more event sources from an existing queue previously acquired * by a call to TEE_Event_OpenQueue. * Panic Reasons: * + If handle is invalid. * + If the sources array does not contain numSources elements. * + If any pointer in sources is NULL. * + If the Implementation detects any error associated with the execution of this function which is not explicitly * associated with a defined return code for this function. * @param[in] numSources: Defines how many sources are provided. * @param[in] sources: An array of TEE_EventSourceHandle. Events from these sources are cleared from the queue. * @param[in] handle: The handle for the queue. * @return TEE_SUCCESS: In case of success. * TEE_ERROR_BAD_STATE: If the handle does not represent a currently open queue. * TEE_ERROR_ITEM_NOT_FOUND: If one or more sources was not attached to the queue. All other sources are dropped. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event which occurred in the * REE while the function was in progress. */ TEE_Result TA_EXPORT TEE_Event_DropSources( uint32_t numSources, _IN_ TEE_EventSourceHandle *sources, _IN_ TEE_EventQueueHandle *handle); /** * The TEE_Event_ListSources function returns information about sources currently attached to a queue. * Panic Reasons: * + If handle is invalid. * + If bufSize is NULL. * + If sources is NULL. * + See section 3.4.4 for reasons for [outbuf] generated panic. * + If the Implementation detects any error associated with the execution of this function which is not explicitly * associated with a defined return code for this function. * @param[in] handle: The handle for the queue. * @param[out] sources: A buffer of at least bufSize bytes that on successful return is overwritten with an array * of TEE_EventSourceHandle structures. * @param[in,out] bufSize: On entry, the size of sources in bytes. * On return, the actual number of bytes in the array. * @return TEE_SUCCESS: In case of success. * TEE_ERROR_OUT_OF_MEMORY: If the system ran out of resources. * TEE_ERROR_SHORT_BUFFER: If the output buffer is not large enough to hold all the sources. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event which occurred in * the REE while the function was in progress. */ TEE_Result TA_EXPORT TEE_Event_ListSources( _IN_ TEE_EventQueueHandle *handle, _OUTBUF_ TEE_EventSourceHandle *sources, size_t *bufSize); /** * The TEE_Event_OpenQueue function claims an exclusive access to TUI resources for the current TA instance. * This function allows for multiple event sources to be reserved. * It is possible for multiple TAs to open queues at the same time provided they do not try to reserve any of the * same resources. An individual TA SHALL NOT open multiple queues; instead, the TA SHOULD use TEE_Event_AddSources * and TEE_Event_DropSources to add and remove event sources from the queue. The TEE_EventQueue will be closed * automatically if no calls to TEE_Event_Wait are made for timeout milliseconds. This has the same guarantees * as the TEE_Wait function. * Panic Reasons: * + If version is invalid. * + If handle is NULL. * + If the sources array does not contain numSources elements. * + If any pointer in sources is NULL. * + If the Implementation detects any error associated with the execution of this function which is not explicitly * associated with a defined return code for this function. * @param[in,out] version: On entry, the highest version of the TEE_Event structure understood by the calling program. * On return, the actual version of the TEE_Event structure that will be added to the queue, * which may be lower than the value requested. * @param[in] numSources: Defines how many sources are provided. * @param[in] timeout: The timeout for this function in milliseconds. * @param[in] sources: An array of TEE_EventSourceHandle, as returned from TEE_Event_ListSources. * @param[out] handle: The handle for this session. This value SHOULD Be Zero on entry and is set if the session is * successfully established and numSources is not zero. * @return TEE_SUCCESS: In case of success. * TEE_ERROR_BUSY: If any requested resource cannot be reserved. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event which occurred in * the REE while the function was in progress. * TEE_ERROR_OLD_VERSION: If the version of the TEE_Event structure requested is not supported. * TEE_ERROR_OUT_OF_MEMORY: If the system ran out of resources. */ TEE_Result TA_EXPORT TEE_Event_OpenQueue( _INOUT_ uint32_t *version, uint32_t numSources, uint32_t timeout, _IN_ TEE_EventSourceHandle *sources, _OUT_ TEE_EventQueueHandle *handle); /** * The TEE_Event_Wait function fetches events that have been returned from a peripheral reserved by TEE_Event_OpenQueue. * Panic Reasons: * + If handle is invalid. * + If events is NULL. * + If numEvents is NULL. * + If dropped is NULL. * + If the Implementation detects any error associated with the execution of this function which is not explicitly * associated with a defined return code for this function. * @param[in] handle: The handle for the queue * @param[in] timeout: The timeout in milliseconds * @param[in,out] events: A pointer to an array of TEE_Event structures * @param[in,out] numEvents: On entry, the maximum number of events to return * On return, the actual number of events returned * @param[out] dropped: A pointer to a count of dropped events * @return TEE_SUCCESS: In case of success. * TEE_ERROR_BAD_STATE: If handle does not represent a currently open queue. * TEE_ERROR_TIMEOUT: If there is no event to return within the timeout. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event which occurred in * the REE while the function was in progress. * TEE_ERROR_CANCEL: If the operation was cancelled by anything other than an event in the REE. */ TEE_Result TA_EXPORT TEE_Event_Wait( _IN_ TEE_EventQueueHandle *handle, uint32_t timeout, _INOUT_ TEE_Event *events, _INOUT_ uint32_t *numEvents, _OUT_ uint32_t *dropped); /** * The TEE_Event_TimerCreate function creates a one-shot timer which, on expiry, will cause * TEE_Event_Timer to be placed onto the event queue designated by handle. * Although the accuracy of period cannot be guaranteed, events are timestamped * if the TA requires an accurate measure of the time between events. * Panic Reasons: * + If handle is invalid. * @param[in] handle: The handle for the queue * @param[in] period: The minimum timer period in milliseconds. The accuracy of the timer period * is subject to the constraints of TEE_Wait * @param[in] payload: A payload chosen by the TA which is returned in the TEE_Event_Timer payload when the timer expires * @return TEE_SUCCESS: In case of success. * TEE_ERROR_BUSY: If any requested resource cannot be reserved. * TEE_ERROR_OUT_OF_MEMORY: If the system ran out of resources. */ TEE_Result TA_EXPORT TEE_Event_TimerCreate( _IN_ TEE_EventQueueHandle *handle, _IN_ uint64_t period, _IN_ uint8_t payload[TEE_MAX_EVENT_PAYLOAD_SIZE]); /*************************************************************** * TUI API Functions * **************************************************************/ /** * The TEE_TUI_BlitDisplaySurface function blits the contents of the surface associated with a display onto that display. * Panic Reasons: * + If display is NULL or does not point to a valid display. * + If surface is NULL or does not point to a valid surface. * + If the Implementation detects any error associated with the execution of this function which is not explicitly * associated with a defined return code for this function. * @param[in] display: The display to update. * @return TEE_SUCCESS: In case of success. * TEE_ERROR_BAD_STATE: If the TUI session has expired. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event which occurred in the * REE while the function was in progress. */ TEE_Result TA_EXPORT TEE_TUI_BlitDisplaySurface(_IN_ TEE_TUIDisplay *display); /** * The TEE_TUI_CloseSession function releases TUI resources previously acquired. * Panic Reasons: TEE_TUI_CloseSession SHALL NOT panic. * @return TEE_SUCCESS: In case of success. * TEE_ERROR_BAD_STATE: If the current TA instance is not within a TUI session initially started by a * successful call to TEE_TUI_InitSessionLow. * TEE_ERROR_BUSY: If the TUI resources are currently in use, i.e. a TUI screen is displayed. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event which * occurred in the REE while the function was in progress. */ TEE_Result TA_EXPORT TEE_TUI_CloseSession(void); /** * The TEE_TUI_DrawRectangle function draws a filled rectangle in a given surface. * Panic Reasons: * + If surface is NULL or does not point to a valid surface. * + If the Implementation detects any error associated with the execution of this function which is not explicitly * associated with a defined return code for this function. * @param[in] surface: A pointer to the surface on which the rectangle will be drawn. * @param[in] x1,y1: The coordinates of one corner of the rectangle (usually the top left). * @param[in] x2,y2: The coordinates of the diagonally opposite (usually the bottom right) corner of the rectangle. * @param[in] color: A 32-bit value containing 8-bit alpha, red, green, and blue values. * @param[in] opacity: The TEE_TUI_SURFACE_OPACITY to apply to this rectangle; * @return TEE_SUCCESS: In case of success. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event which occurred in the * REE while the function was in progress. */ TEE_Result TA_EXPORT TEE_TUI_DrawRectangle( _IN_ TEE_TUISurface *surface, uint32_t x1, uint32_t y1, uint32_t x2, uint32_t y2, uint32_t color, _IN_ TEE_TUI_SURFACE_OPACITY opacity); /** * The TEE_TUI_GetDisplayInformation function retrieves information about a display, including pixel size, * physical size, and bit depth. * Panic Reasons: * + If version is NULL. * + If displayInfo is NULL. * + If display is NULL. * + If the Implementation detects any error associated with the execution of this function which is not explicitly * associated with a defined return code for this function. * @param[in] displayNumber: The number of the display whose information is to be retrieved. * @param[in,out] version: On entry, the highest version of the TEE_TUIDisplayInfo structure understood by the calling program. * On return, the actual version of the TEE_TUIDisplayInfo structure returned, which may be lower than * the value requested. * @param[out] displayInfo: A pointer to a TEE_TUIDisplayInfo structure. * On return, this structure is populated by the TUI implementation. * @param[out] display: A pointer to the TEE_TUIDisplay structure for this display. * This structure is populated by the TUI implementation. * @return TEE_SUCCESS: In case of success. * TEE_ERROR_OLD_VERSION: If the version of the TEE_TUIDisplayInfo structure requested is not supported. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event which occurred in * the REE while the function was in progress. * TEE_ERROR_ITEM_NOT_FOUND: If the requested display is not present. * TEE_ERROR_OUT_OF_MEMORY: If the system ran out of resources. */ TEE_Result TA_EXPORT TEE_TUI_GetDisplayInformation( uint32_t displayNumber, _INOUT_ uint32_t *version, _OUT_ TEE_TUIDisplayInfo *displayInfo, _OUT_ TEE_TUIDisplay *display); /** * The TEE_TUI_GetDisplaySurface function yields a surface which will be displayed when TEE_TUI_BlitDisplaySurface is called. * Default session display buffer will be set to zero (all color bytes and alpha channel * will be set to 0x00). * Fully opaque picture in display surface can be set, for example, by calling * TEE_TUI_DrawRectangle() with appropriate color, alpha = 0xFF and appropriate opacity mode * TEE_TUI_SURFACE_OPACITY_OPAQUE. * Panic Reasons: * + If display is NULL or does not point to a valid display. * + If surface is NULL. * + If the Implementation detects any error associated with the execution of this function which is not * explicitly associated with a defined return code for this function. * @param[in] display: The display to be opened. * @param[out] surface: This surface associated with this display. * @return TEE_SUCCESS: In case of success. * TEE_ERROR_BAD_STATE: If the TUI session has expired. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event which occurred in * the REE while the function was in progress. */ TEE_Result TA_EXPORT TEE_TUI_GetDisplaySurface( _IN_ TEE_TUIDisplay *display, _OUT_ TEE_TUISurface *surface); /** * The TEE_TUI_GetPNGInformation function returns the height, width, and color type * of a given PNG image. * Panic Reasons: * + If png is NULL or cannot be interpreted as a valid PNG image. * + If width is NULL. * + If height is NULL. * + If colorType is NULL. * + If the Implementation detects any error associated with the execution of this function * which is not explicitly associated with a defined return code for this function. * @param[in] png: A pointer to TEE_TUIImage containing an image. * @param[out] width: The width in pixels of the image. On entry, SHOULD be set to zero. * Will be populated on return. * @param[out] height: The height in pixels of the image. On entry, SHOULD be set to zero. * Will be populated on return. * @param[out] colorType: The color type of the image. On entry, SHOULD be set to zero. * Will be populated on return: * Grayscale (0) up to 8 bits depth, Truecolor (2) up to 24 bits * @return TEE_SUCCESS: In case of success. * TEE_ERROR_BAD_FORMAT: If the image format is not supported. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event * which occurred in the REE while the function was in progress. * TEE_ERROR_OUT_OF_MEMORY: If the system ran out of resources. */ TEE_Result TA_EXPORT TEE_TUI_GetPNGInformation( _IN_ TEE_TUIImage *png, _OUT_ uint32_t *width, _OUT_ uint32_t *height, _OUT_ uint32_t *colorType); /** * The TEE_TUI_GetSurface function creates a new surface of the given width and height. * Panic Reasons: * + If stride is less than width. * + If out is NULL. * + If the Implementation detects any error associated with the execution of this function * which is not explicitly associated with a defined return code for this function. * @param[in] width: The width of the surface in pixels. * @param[in] height: The height of the surface in pixels. * @param[in] stride: The stride of the surface in pixels. * @param[out] out: Pointer to the new surface. This may be NULL on entry. * @return TEE_SUCCESS: In case of success. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event * which occurred in the REE while the function was in progress. * TEE_ERROR_OUT_OF_MEMORY: If the system ran out of resources. */ TEE_Result TA_EXPORT TEE_TUI_GetSurface( uint32_t width, uint32_t height, uint32_t stride, _OUT_ TEE_TUISurface *out); /** * The TEE_TUI_GetSurfaceBuffer function yields the buffer for writing to, and reading from, * this surface. * Panic Reasons: * + If version is NULL. * + If surface is NULL. * + If buf is NULL. * + If surface is the surface associated with a display. * @param[in,out] version: On entry, the highest version of the TEE_TUISurfaceBuffer structure * understood by the calling program. * On return, the actual version returned, which may be lower * than the value requested. * @param[in] surface: An existing surface. * @param[out] buf: A buffer with the height and width of the given surface. * @return TEE_SUCCESS: In case of success. * TEE_ERROR_OLD_VERSION: If the version of the TEE_TUISurfaceBuffer structure requested * is not supported. * TEE_ERROR_BAD_STATE: If the surface does not exist or has been released. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event * which occurred in the REE while the function was in progress. * TEE_ERROR_OUT_OF_MEMORY: If the system ran out of resources. */ TEE_Result TA_EXPORT TEE_TUI_GetSurfaceBuffer( _INOUT_ uint32_t *version, _IN_ TEE_TUISurface *surface, _OUT_ TEE_TUISurfaceBuffer *buf); /** * The TEE_TUI_GetSurfaceInformation function returns information about a surface. * Panic Reasons: * + If version is NULL. * + If surface is NULL or is not a pointer to a valid surface. * + If info is NULL. * + If the Implementation detects any error associated with the execution of this function * which is not explicitly associated with a defined return code for this function. * @param[in,out] version: On entry, the highest version of the TEE_TUISurfaceInfo structure * understood by the calling program. * On return, the actual version returned, which may be lower * than the value requested. * @param[in] surface: A pointer to the surface whose information is to be retrieved. * @param[out] info: A pointer to the structure holding information about this surface. * @return TEE_SUCCESS: In case of success. * TEE_ERROR_OLD_VERSION: If the version the TEE_TUISurfaceInfo structure requested * is not supported. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event * which occurred in the REE while the function was in progress. * TEE_ERROR_OUT_OF_MEMORY: If the system ran out of resources. */ TEE_Result TA_EXPORT TEE_TUI_GetSurfaceInformation( _INOUT_ uint32_t *version, _IN_ TEE_TUISurface *surface, _OUT_ TEE_TUISurfaceInfo *info); /** * The TEE_TUI_InitSessionLow function atomically claims an exclusive access to TUI displays and TUI input * peripherals for the current TA instance. * Panic Reasons: * + If displays is NULL or does not contain numDisplays elements. * + If TEE_TUI_INIT_SESSION_LOW_FLAG_REQUIREINDICATOR is set when gpd.tee.tui.low.securityIndicator is false. * + If the Implementation detects any error associated with the execution of this function which is not explicitly * associated with a defined return code for this function. * @param[in] numDisplays: Defines how many display structures are provided – this SHALL be * less than gpd.tee.tui.low.numDisplays. * @param[in] timeout: The timeout for this function in milliseconds – overrides * gpd.tee.tui.low.session.timeout if timeout is smaller. * @param[in] flags: One or more TEE_TUI_INIT_SESSION_LOW_FLAGS XORed together; see section 4.3.14. * @param[in] displays: An array of TEE_TUIDisplay pointers; see section 4.5.13. * @param[in] numPeripherals: The number of entries in the TEE_PeripheralDescriptor buffer pointed to by peripherals. * @param[in,out] peripherals: A pointer to a buffer of numPeripherals instances of TEE_PeripheralDescriptor. * @return TEE_SUCCESS: In case of success. * TEE_ERROR_BUSY: If another TA has a lock on the resources needed. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event which occurred in * the REE while the function was in progress. * TEE_ERROR_OUT_OF_MEMORY: If the system ran out of resources. */ TEE_Result TA_EXPORT TEE_TUI_InitSessionLow( uint32_t numDisplays, uint32_t timeout, uint32_t flags, _IN_ TEE_TUIDisplay *displays, const uint32_t numPeripherals, _INOUT_ TEE_PeripheralDescriptor *peripherals); /** * The TEE_TUI_ReleaseSurface function destroys memory associated with the surface. * Panic Reasons: * + If surface is NULL. * + If surface is not releasable; that is, it was allocated by TEE_TUI_GetDisplaySurface. * + If the Implementation detects any error associated with the execution of this function * which is not explicitly associated with a defined return code for this function. * @param[in] surface: The surface to release. * @return TEE_SUCCESS: In case of success. * TEE_ERROR_BAD_STATE: If the surface does not exist or has been released. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event * which occurred in the REE while the function was in progress. */ TEE_Result TA_EXPORT TEE_TUI_ReleaseSurface(_IN_ TEE_TUISurface *surface); /** * The TEE_TUI_SetPNG function renders a PNG image onto a surface at a given location. * Panic Reasons: * + If surface is NULL. * + If png is NULL. * + If the Implementation detects any error associated with the execution of this function which is not explicitly * associated with a defined return code for this function. * @param[in] surface: A pointer to the surface in which to draw the image. * @param[in] png: A pointer to a TEE_TUIImage structure containing a PNG image. * @param[in] x,y: The coordinates of the top left pixel of the image. * @param[in] opacity: The TEE_TUI_SURFACE_OPACITY to apply to the image; see section 4.3.16. * @return TEE_SUCCESS: In case of success. * TEE_ERROR_BAD_FORMAT: If the image is not compliant with PNG format or if the image format is not supported. * TEE_ERROR_BAD_STATE: If the surface is not valid. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event which occurred in * the REE while the function was in progress. * TEE_ERROR_OUT_OF_MEMORY: If the system ran out of resources. */ TEE_Result TA_EXPORT TEE_TUI_SetPNG( _IN_ TEE_TUISurface *surface, _IN_ TEE_TUIImage *png, _IN_ uint32_t x, _IN_ uint32_t y, _IN_ TEE_TUI_SURFACE_OPACITY opacity); /** * The TEE_TUI_TransformSurface function takes an image in the input surface and performs the specified * transformation on the portion of the image whose top left corner is at x_source, y_source with width width * and height height. * Panic Reasons: * + If source is NULL or does not point to a valid surface. * + If destination is NULL or does not point to a valid surface. * + If width is NULL. * + If height is NULL. * + If the Implementation detects any error associated with the execution of this function which is not explicitly * associated with a defined return code for this function. * @param[in] source: The TEE_TUISurface to read input data from. * @param[in,out] destination: The TEE_TUISurface to write data to. This SHALL NOT be the same surface as source. * @param[in] x_source: The x-coordinate in *source of the top left hand corner of the data to transform. * @param[in] y_source: The y-coordinate in *source of the top left hand corner of the data to transform. * @param[in] width: The width in pixels of the portion of the image to transform. * @param[in] height: The height in pixels of the portion of the image to transform. * @param[in] x_dest: The x-coordinate in *destination of the top left hand corner of the resultant image. * @param[in] y_dest: The y-coordinate in *destination of the top left hand corner of the resultant image. * @param[in] opacity: Determines how to blend pixels in the source and destination. * @param[in] operation: The operation to perform on the image. This is a bitwise OR of TEE_TUI_OPERATION values. * @return TEE_SUCCESS: In case of success. * TEE_ERROR_BAD_STATE: If the surface does not exist or has been released. * TEE_ERROR_EXTERNAL_CANCEL: If the operation has been cancelled by an external event which occurred in the * REE while the function was in progress. * TEE_ERROR_OUT_OF_MEMORY: If the system ran out of resources. */ TEE_Result TA_EXPORT TEE_TUI_TransformSurface( _IN_ TEE_TUISurface *source, _INOUT_ TEE_TUISurface *destination, _IN_ uint32_t x_source, _IN_ uint32_t y_source, _IN_ uint32_t width, _IN_ uint32_t height, _IN_ uint32_t x_dest, _IN_ uint32_t y_dest, _IN_ TEE_TUI_SURFACE_OPACITY opacity, _IN_ TEE_TUI_OPERATION operation); #endif //TEE_CORE_API_EVENT /** @} */