--- /dev/null
+/*\r
+Copyright (c) 2018, MIPI Alliance, Inc.\r
+All rights reserved.\r
+\r
+Redistribution and use in source and binary forms, with or without\r
+modification, are permitted provided that the following conditions\r
+are met:\r
+\r
+* Redistributions of source code must retain the above copyright\r
+ notice, this list of conditions and the following disclaimer.\r
+\r
+* Redistributions in binary form must reproduce the above copyright\r
+ notice, this list of conditions and the following disclaimer in\r
+ the documentation and/or other materials provided with the\r
+ distribution.\r
+\r
+* Neither the name of the copyright holder nor the names of its\r
+ contributors may be used to endorse or promote products derived\r
+ from this software without specific prior written permission.\r
+\r
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS\r
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT\r
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR\r
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT\r
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,\r
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT\r
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\r
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\r
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\r
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\r
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\r
+*/\r
+\r
+/*\r
+ * Contributors:\r
+ * Norbert Schulz (Intel Corporation) - Initial API and implementation\r
+ */\r
+\r
+#ifndef MIPI_SYST_H_INCLUDED\r
+#define MIPI_SYST_H_INCLUDED\r
+\r
+/* SyS-T API version information\r
+ */\r
+#define MIPI_SYST_VERSION_MAJOR 1 /**< Major version, incremented if API changes */\r
+#define MIPI_SYST_VERSION_MINOR 0 /**< Minor version, incremented on compatible extensions */\r
+#define MIPI_SYST_VERSION_PATCH 0 /**< Patch for existing major, minor, usually 0 */\r
+\r
+/** Define SyS-T API conformance level\r
+ *\r
+ * 10 = minimal (only short events)\r
+ * 20 = low overhead (exluding varag functions and CRC32)\r
+ * 30 = full implementation\r
+ */\r
+#define MIPI_SYST_CONFORMANCE_LEVEL 30\r
+\r
+/** Compute SYS-T version value\r
+ *\r
+ * Used to compare SYS-T Major.Minor.patch versions numerically at runtime.\r
+ *\r
+ * @param ma major version number\r
+ * @param mi minor version number\r
+ * @param p patch version number\r
+ *\r
+ * Example:\r
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}\r
+ *\r
+ * #if MIPI_SYST_VERSION_CODE >= MIPI_SYST_MAKE_VERSION_CODE(1,5,0)\r
+ * // do what only >= 1.5.x supports\r
+ * #endif\r
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r
+ */\r
+#define MIPI_SYST_MAKE_VERSION_CODE(ma, mi, p) (((ma) << 16) | ((mi)<<8) | (p))\r
+\r
+/** Numeric SYS-T version code */\r
+#define MIPI_SYST_VERSION_CODE MIPI_SYST_MAKE_VERSION_CODE(\\r
+ MIPI_SYST_VERSION_MAJOR,\\r
+ MIPI_SYST_VERSION_MINOR,\\r
+ MIPI_SYST_VERSION_PATCH)\r
+\r
+/* Macros to trick numeric values like __LINE__ into a string\r
+ */\r
+#define _MIPI_SYST_STRINGIFY(x) #x\r
+#define _MIPI_SYST_CPP_TOSTR(x) _MIPI_SYST_STRINGIFY(x)\r
+\r
+#define _MIPI_SYST_VERSION_STRING(a, b, c)\\r
+ _MIPI_SYST_CPP_TOSTR(a)"."_MIPI_SYST_CPP_TOSTR(b)"."_MIPI_SYST_CPP_TOSTR(c)\r
+\r
+/** Textual version string */\r
+#define MIPI_SYST_VERSION_STRING \\r
+ _MIPI_SYST_VERSION_STRING(\\r
+ MIPI_SYST_VERSION_MAJOR,\\r
+ MIPI_SYST_VERSION_MINOR,\\r
+ MIPI_SYST_VERSION_PATCH)\r
+\r
+#ifndef MIPI_SYST_COMPILER_INCLUDED\r
+#include "mipi_syst/compiler.h"\r
+#endif\r
+\r
+/* String hash macros for compile time computation of catalog ID's.\r
+ * Notes:\r
+ * These macros will only be used with optimized builds, otherwise\r
+ * a lot of runtime code will be generated.\r
+ *\r
+ * Only the last 64 bytes of the string are considered for hashing\r
+ */\r
+#define _MIPI_SYST_HASH1(s,i,x,l) (x*65599u+(mipi_syst_u8)s[(i)<(l)?((l)-1-(i)):(l)])\r
+#define _MIPI_SYST_HASH4(s,i,x,l) _MIPI_SYST_HASH1(s,i,_MIPI_SYST_HASH1(s,i+1,_MIPI_SYST_HASH1(s,i+2,_MIPI_SYST_HASH1(s,i+3,x,l),l),l),l)\r
+#define _MIPI_SYST_HASH16(s,i,x,l) _MIPI_SYST_HASH4(s,i,_MIPI_SYST_HASH4(s,i+4,_MIPI_SYST_HASH4(s,i+8,_MIPI_SYST_HASH4(s,i+12,x,l),l),l),l)\r
+#define _MIPI_SYST_HASH64(s,i,x,l) _MIPI_SYST_HASH16(s,i,_MIPI_SYST_HASH16(s,i+16,_MIPI_SYST_HASH16(s,i+32,_MIPI_SYST_HASH16(s,i+48,x,l),l),l),l)\r
+\r
+#define _MIPI_SYST_HASH_x65599(s,l) ((mipi_syst_u32)_MIPI_SYST_HASH64(s,0,0,l))\r
+\r
+#define _MIPI_SYST_HASH_AT_CPP_TIME(str, offset) (_MIPI_SYST_HASH_x65599(str, sizeof(str)-1) + (offset))\r
+#define _MIPI_SYST_HASH_AT_RUN_TIME(str, offset) (mipi_syst_hash_x65599(str, sizeof(str)-1) + (offset))\r
+\r
+#if defined(_MIPI_SYST_OPTIMIZER_ON)\r
+#define MIPI_SYST_HASH(a, b) _MIPI_SYST_HASH_AT_CPP_TIME((a), (b))\r
+#else\r
+#define MIPI_SYST_HASH(a, b) _MIPI_SYST_HASH_AT_RUN_TIME((a),(b))\r
+#endif\r
+\r
+#if defined(__cplusplus)\r
+extern "C" {\r
+#endif\r
+\r
+/** Major Message Types\r
+ */\r
+enum mipi_syst_msgtype {\r
+ MIPI_SYST_TYPE_BUILD = 0, /**< client build id message */\r
+ MIPI_SYST_TYPE_SHORT32 = 1, /**< value only message */\r
+ MIPI_SYST_TYPE_STRING = 2, /**< text message output */\r
+ MIPI_SYST_TYPE_CATALOG = 3, /**< catalog message output */\r
+ MIPI_SYST_TYPE_RAW = 6, /**< raw binary data */\r
+ MIPI_SYST_TYPE_SHORT64 = 7, /**< value only message */\r
+ MIPI_SYST_TYPE_CLOCK = 8, /**< clock sync message */\r
+\r
+ MIPI_SYST_TYPE_MAX\r
+};\r
+\r
+/** MIPI_SYST_TYPE_DEBUG_STRING Sub-Types\r
+ */\r
+enum mipi_syst_subtype_string {\r
+ MIPI_SYST_STRING_GENERIC = 1, /**< string generic debug */\r
+ MIPI_SYST_STRING_FUNCTIONENTER = 2, /**< string is function name */\r
+ MIPI_SYST_STRING_FUNCTIONEXIT = 3, /**< string is function name */\r
+ MIPI_SYST_STRING_INVALIDPARAM = 5, /**< invalid SyS-T APIcall */\r
+ MIPI_SYST_STRING_ASSERT = 7, /**< Software Assert: failure */\r
+ MIPI_SYST_STRING_PRINTF_32 = 11, /**< printf with 32-bit packing */\r
+ MIPI_SYST_STRING_PRINTF_64 = 12, /**< printf with 64-bit packing */\r
+\r
+ MIPI_SYST_STRING_MAX\r
+};\r
+\r
+/** MIPI_SYST_TYPE_CATALOG Sub-Types\r
+ */\r
+enum mipi_syst_subtype_catalog {\r
+ MIPI_SYST_CATALOG_ID32_P32 = 1, /**< 32-bit catalog ID, 32-bit packing */\r
+ MIPI_SYST_CATALOG_ID64_P32 = 2, /**< 64-bit catalog ID, 32-bit packing */\r
+ MIPI_SYST_CATALOG_ID32_P64 = 5, /**< 32-bit catalog ID, 64-bit packing */\r
+ MIPI_SYST_CATALOG_ID64_P64 = 6, /**< 64-bit catalog ID, 64-bit packing */\r
+\r
+ MIPI_SYST_CATALOG_MAX\r
+};\r
+\r
+/** MIPI_SYST_TYPE_CLOCK Sub-Types\r
+ */\r
+enum mipi_syst_subtype_clock{\r
+ MIPI_SYST_CLOCK_TRANSPORT_SYNC = 1, /**< SyS-T clock & frequency sync */\r
+ MIPI_SYST_CLOCK_MAX\r
+};\r
+\r
+enum mipi_syst_subtype_build {\r
+ MIPI_SYST_BUILD_ID_COMPACT32 = 0, /**< compact32 build id */\r
+ MIPI_SYST_BUILD_ID_COMPACT64 = 1, /**< compact64 build id */\r
+ MIPI_SYST_BUILD_ID_LONG = 2, /**< normal build message */\r
+ MIPI_SYST_BUILD_MAX\r
+};\r
+\r
+struct mipi_syst_header;\r
+struct mipi_syst_handle;\r
+struct mipi_syst_scatter_prog;\r
+\r
+/** 128-bit GUID style message origin ID */\r
+struct mipi_syst_guid {\r
+ union {\r
+ mipi_syst_u8 b[16];\r
+ mipi_syst_u64 ll[2];\r
+ } u;\r
+};\r
+\r
+/** GUID initializer code\r
+ *\r
+ * This macro simplifies converting a GUID from its string representation\r
+ * into the mipi_syst_guid data structure. The following example shows\r
+ * how the values from a GUID string are used with the macro. Each numeric\r
+ * component from the GUID string gets converted into a hex value parameter\r
+ * when invoking the macro.\r
+ *\r
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}\r
+ *\r
+ * // Guid: f614b99d-99a1-4c04-8c30-90999ab5fe05\r
+ *\r
+ * struct mipi_syst_guid guid =\r
+ * MIPI_SYST_GEN_GUID(0xf614b99d, 0x99a1, 0x4c04, 0x8c30, 0x90999ab5fe05);\r
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r
+ */\r
+#define MIPI_SYST_GEN_GUID(l1, w1, w2, w3, l2) \\r
+ {{\\r
+ (mipi_syst_u8)((mipi_syst_u32)(l1) >> 24), \\r
+ (mipi_syst_u8)((mipi_syst_u32)(l1) >> 16), \\r
+ (mipi_syst_u8)((mipi_syst_u32)(l1) >> 8), \\r
+ (mipi_syst_u8)((mipi_syst_u32)(l1) >> 0), \\r
+ (mipi_syst_u8)((mipi_syst_u16)(w1) >> 8), \\r
+ (mipi_syst_u8)((mipi_syst_u16)(w1) >> 0), \\r
+ (mipi_syst_u8)((mipi_syst_u16)(w2) >> 8), \\r
+ (mipi_syst_u8)((mipi_syst_u16)(w2) >> 0), \\r
+ (mipi_syst_u8)((mipi_syst_u16)(w3) >> 8), \\r
+ (mipi_syst_u8)((mipi_syst_u16)(w3) >> 0), \\r
+ (mipi_syst_u8)((mipi_syst_u64)(l2) >> 40), \\r
+ (mipi_syst_u8)((mipi_syst_u64)(l2) >> 32), \\r
+ (mipi_syst_u8)((mipi_syst_u64)(l2) >> 24), \\r
+ (mipi_syst_u8)((mipi_syst_u64)(l2) >> 16), \\r
+ (mipi_syst_u8)((mipi_syst_u64)(l2) >> 8), \\r
+ (mipi_syst_u8)((mipi_syst_u64)(l2) >> 0) \\r
+ }}\r
+\r
+ /** SyS-T client origin data\r
+ *\r
+ * This structure holds the GUID or header origin and unit data\r
+ * used by SyS-T handles. The structure gets passed into the handle\r
+ * creation functions to initialize the values that identify clients.\r
+ * @see MIPI_SYST_SET_HANDLE_GUID_UNIT\r
+ * @see MIPI_SYST_SET_HANDLE_MODULE_UNIT\r
+ * @see MIPI_SYST_SET_HANDLE_ORIGIN\r
+ */\r
+struct mipi_syst_origin {\r
+ struct mipi_syst_guid guid; /**< origin GUID or module value */\r
+ mipi_syst_u16 unit; /**< unit value */\r
+};\r
+\r
+/** Origin structure initializer code using GUID\r
+*\r
+* This macro simplifies initializing a mipi_syst_origin structure. The\r
+* first 5 parameters are GUID values as used by the MIPI_SYST_GEN_GUID\r
+* macro. The last parameter is the unit value (11-Bits).\r
+* @see MIPI_SYST_GEN_GUID\r
+*\r
+*\r
+* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}\r
+*\r
+* // Guid: {494E5443-B659-45AF-B786-9DB0786248AE}\r
+\r
+*\r
+* struct mipi_syst_origin = origin\r
+* MIPI_SYST_GEN_ORIGIN_GUID(\r
+* 0x494E5443, 0xB659, 0x45AF, 0xB786, 0x9DB0786248AE,\r
+* 0x1);\r
+* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r
+*/\r
+#define MIPI_SYST_GEN_ORIGIN_GUID(l1, w1, w2, w3, l2 , u) \\r
+ {\\r
+ MIPI_SYST_GEN_GUID(l1, w1, w2, w3, l2) ,\\r
+ u\\r
+ }\r
+\r
+/** Origin structure initializer code using header module value\r
+*\r
+* This macro simplifies initializing a mipi_syst_origin structure. The\r
+* first parameter is the header origin value (7-Bits). The second parameter\r
+* is the unit value (4-bits)\r
+* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}\r
+*\r
+* // Guid: {494E5443-B659-45AF-B786-9DB0786248AE}\r
+\r
+* #define MODULE_X 0x10\r
+* struct mipi_syst_origin =\r
+* MIPI_SYST_GEN_ORIGIN_MODULE(MODULE_X, 0x1);\r
+* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r
+*/\r
+#define MIPI_SYST_GEN_ORIGIN_MODULE(m , u) \\r
+ {\\r
+ MIPI_SYST_GEN_GUID(0,0,0, ((mipi_syst_u16)(m & 0x7F)) << 8, 0 ),\\r
+ u\\r
+ }\r
+/**\r
+ * Global state initialization hook definition\r
+ *\r
+ * This function gets called in the context of the mipi_syst_init() API\r
+ * function after the generic state members of the global state\r
+ * structure syst_hdr have been setup. It's purpose is to initialize the\r
+ * platform dependent portion of the state and other necessary\r
+ * platform specific initialization steps.\r
+ *\r
+ * @param systh Pointer to global state structure\r
+ * @param p user defined value or pointer to data\r
+ * @see mipi_syst_header\r
+ */\r
+typedef void (MIPI_SYST_CALLCONV *mipi_syst_inithook_t)(struct mipi_syst_header *systh,\r
+ const void *p);\r
+\r
+/**\r
+ * Global state destroy hook definition\r
+ *\r
+ * This function gets called in the context of the mipi_syst_destroy() API\r
+ * function before the generic state members of the global state\r
+ * structure syst_hdr have been destroyed. Its purpose is to free resources\r
+ * used by the platform dependent portion of the global state.\r
+ *\r
+ * @param systh Pointer to global state structure\r
+ */\r
+typedef void (MIPI_SYST_CALLCONV *mipi_syst_destroyhook_t)(struct mipi_syst_header *systh);\r
+\r
+/**\r
+ * SyS-T handle state initialization hook definition\r
+ *\r
+ * This function gets called in the context of IO handle generation.\r
+ * Its purpose is to initialize the platform dependent portion of\r
+* the handle and other necessary platform specific initialization steps.\r
+ *\r
+ * @param systh Pointer to new SyS-T handle\r
+ * @see syst_handle_t\r
+ */\r
+typedef void (*mipi_syst_inithandle_hook_t)(struct mipi_syst_handle *systh);\r
+\r
+/**\r
+ * SyS-T handle state release hook definition\r
+ *\r
+ * This function gets called when a handle is about to be destroyed..\r
+ * Its purpose is to free any resources allocated during the handle\r
+ * generation.\r
+ *\r
+ * @param systh Pointer to handle that is destroyed\r
+ * @see syst_handle_t\r
+ */\r
+typedef void (*mipi_syst_releasehandle_hook_t)(struct mipi_syst_handle *systh);\r
+\r
+/**\r
+ * Low level message write routine definition\r
+ *\r
+ * This function is called at the end of an instrumentation API to output\r
+ * the raw message data.\r
+ *\r
+ * @param systh pointer to a SyS-T handle structure used in the API call,\r
+ * @param scatterprog pointer to a list of scatter write instructions that\r
+ * encodes how to convert the descriptor pointer by\r
+ * pdesc into raw binary data. This list doesn't include\r
+ * the mandatory first 32 tag byte value pointed by pdesc.\r
+ * @param pdesc pointer to a message descriptor, which containing at least\r
+ * the 32-bit message tag data\r
+ */\r
+typedef void (*mipi_syst_msg_write_t)(\r
+ struct mipi_syst_handle *systh,\r
+ struct mipi_syst_scatter_prog *scatterprog,\r
+ const void *pdesc);\r
+\r
+#ifdef __cplusplus\r
+} /* extern C */\r
+#endif\r
+#ifndef MIPI_SYST_PLATFORM_INCLUDED\r
+\r
+/**\r
+ * @defgroup PCFG_Config Platform Feature Configuration Defines\r
+ *\r
+ * Defines to customize the SyS-T feature set to match the platform needs.\r
+ *\r
+ * Each optional library feature can be disabled by not defining the related\r
+ * MIPI_SYST_PCFG_ENABLE define. Removing unused features in this way reduces\r
+ * both memory footprint and runtime overhead of SyS-T.\r
+ */\r
+\r
+/**\r
+ * @defgroup PCFG_Global Platform Wide Configuration\r
+ * @ingroup PCFG_Config\r
+ *\r
+ * These defines enable global features in the SyS-T library.\r
+ * @{\r
+ */\r
+\r
+\r
+ /**\r
+ * Extend Platform global SyS-T data state\r
+ *\r
+ * This define extends the global SyS-T state data structure\r
+ * mipi_syst_header with platform private content. A platform typically\r
+ * stores data for SyS-T handle creation processing in this structure.\r
+ *\r
+ * Note: This data is not touched by the library code itself, but typically\r
+ * is used by platform hook functions for handle creation and destruction.\r
+ * **These hook function calls are not lock protected and may happen\r
+ * concurrently!** The hook functions need to implement locking if they\r
+ * modify the platform state data.\r
+ *\r
+ * The platform example uses #mipi_syst_platform_state as data state extension.\r
+ */\r
+#define MIPI_SYST_PCFG_ENABLE_PLATFORM_STATE_DATA\r
+#undef MIPI_SYST_PCFG_ENABLE_PLATFORM_STATE_DATA\r
+/**\r
+ * Extend SyS-T handle data state\r
+ *\r
+ * This define extends the SyS-T handle state data structure\r
+ * mipi_syst_handle with platform private content. A platform typically\r
+ * stores data for fast trace hardware access in the handle data, for\r
+ * example a volatile pointer to an MMIO space.\r
+ *\r
+ * The platform example uses #mipi_syst_platform_handle as handle state\r
+ * extension.\r
+ */\r
+#define MIPI_SYST_PCFG_ENABLE_PLATFORM_HANDLE_DATA\r
+\r
+/**\r
+ * Enable HEAP usage for handle generation\r
+ *\r
+ * This macro tells the SyS-T library to enable the heap allocation handle\r
+ * creation API #MIPI_SYST_ALLOC_HANDLE.\r
+ * The platform must provide the macros #MIPI_SYST_HEAP_MALLOC and\r
+ * #MIPI_SYST_HEAP_FREE to point SyS-T to the platform malloc and free\r
+ * functions.\r
+ *\r
+ * Note: In OS kernel space environments, you must use unpaged memory\r
+ * allocation functions.\r
+ */\r
+#define MIPI_SYST_PCFG_ENABLE_HEAP_MEMORY\r
+#undef MIPI_SYST_PCFG_ENABLE_HEAP_MEMORY\r
+/* MSVC and GNU compiler 64-bit mode */\r
+\r
+/**\r
+ * Enable 64-bit instruction addresses\r
+ *\r
+ * Set this define if running in 64-bit code address space.\r
+ */\r
+#if defined(_WIN64) || defined(__x86_64__) || defined (__LP64__)\r
+#define MIPI_SYST_PCFG_ENABLE_64BIT_ADDR\r
+#endif\r
+/**\r
+ * Enable atomic 64-bit write operations\r
+ *\r
+ * Set this define if your platform supports an atomic 64-bit data write\r
+ * operation. This results in fewer MMIO accesses.The SyS-T library\r
+ * defaults to 2 consecutive 32-Bit writes otherwise.\r
+ */\r
+#if defined(_WIN64) || defined(__x86_64__) || defined (__LP64__)\r
+#define MIPI_SYST_PCFG_ENABLE_64BIT_IO\r
+#endif\r
+\r
+/**\r
+ * Enable helper function code inlining\r
+ *\r
+ * Set this define if speed is more important than code size on your platform.\r
+ * It causes several helper function to get inlined, producing faster, but\r
+ * also larger, code.\r
+ */\r
+#define MIPI_SYST_PCFG_ENABLE_INLINE\r
+\r
+/** @} */\r
+\r
+/**\r
+ * @defgroup PCFG_ApiSet Supported API sets\r
+ * @ingroup PCFG_Config\r
+ *\r
+ * These defines enable API sets in the SyS-T library. They are set by default\r
+ * depending on the SyS-T API conformance level. The level is specified using\r
+ * the define #MIPI_SYST_CONFORMANCE_LEVEL.\r
+ * @{\r
+ */\r
+\r
+#if MIPI_SYST_CONFORMANCE_LEVEL > 10\r
+ /**\r
+ * Use SyS-T scatter write output function\r
+ *\r
+ * The library comes with an output routine that is intended to write data out\r
+ * to an MMIO space. It simplifies a SyS-T platform integration as\r
+ * only low-level access macros must be provided for outputting data. These\r
+ * macros follow MIPI System Trace Protocol (STP) naming convention, also\r
+ * non STP generators can use this interface.\r
+ *\r
+ * These low level output macros are:\r
+ *\r
+ * #MIPI_SYST_OUTPUT_D32MTS, #MIPI_SYST_OUTPUT_D64MTS,\r
+ * #MIPI_SYST_OUTPUT_D32TS, #MIPI_SYST_OUTPUT_D64,\r
+ * #MIPI_SYST_OUTPUT_D32, #MIPI_SYST_OUTPUT_D16, #MIPI_SYST_OUTPUT_D8 and\r
+ * #MIPI_SYST_OUTPUT_FLAG\r
+ *\r
+ * Note: This version of the write function always starts messages\r
+ * using a 32-bit timestamped record also other sized timestamped\r
+ * packets are allowed by the SyS-T specification.\r
+ */\r
+#define MIPI_SYST_PCFG_ENABLE_DEFAULT_SCATTER_WRITE\r
+\r
+/**\r
+ * Enable the Catalog API for 32-Bit Catalog IDs.\r
+ */\r
+#define MIPI_SYST_PCFG_ENABLE_CATID32_API\r
+\r
+/**\r
+ * Enable the Catalog API for 64-Bit Catalog IDs.\r
+ */\r
+#define MIPI_SYST_PCFG_ENABLE_CATID64_API\r
+\r
+/**\r
+ * Enable plain UTF-8 string output APIs.\r
+ */\r
+#define MIPI_SYST_PCFG_ENABLE_STRING_API\r
+\r
+/**\r
+ * Enable raw data output APIs\r
+ */\r
+#define MIPI_SYST_PCFG_ENABLE_WRITE_API\r
+\r
+/**\r
+ * Enable Build API\r
+ */\r
+#define MIPI_SYST_PCFG_ENABLE_BUILD_API\r
+#endif /* MIPI_SYST_CONFORMANCE_LEVEL > 10 */\r
+\r
+#if MIPI_SYST_CONFORMANCE_LEVEL > 20\r
+ /**\r
+ * Enable printf API support\r
+ *\r
+ * Note:\r
+ * Enabling printf requires compiler var_arg support as defined by the\r
+ * header files stdarg.h stddef.h.\r
+ */\r
+\r
+#define MIPI_SYST_PCFG_ENABLE_PRINTF_API\r
+#undef MIPI_SYST_PCFG_ENABLE_PRINTF_API\r
+/**\r
+ * Maximum size of printf payload in bytes.\r
+ * Adjust this value if larger strings shall be supported by the library.\r
+ * The buffer space is located in stack memory when calling one of the printf\r
+ * style APIs.\r
+ */\r
+#define MIPI_SYST_PCFG_PRINTF_ARGBUF_SIZE 1024\r
+\r
+#endif /* #if MIPI_SYST_CONFORMANCE_LEVEL > 20 */\r
+\r
+/* @} */\r
+\r
+/**\r
+ * @defgroup PCFG_Message Optional Message Attributes\r
+ * @ingroup PCFG_Config\r
+ *\r
+ * These defines enable optional message components. They are set by default\r
+ * depending on the SyS-T API conformance level. The level is specified using\r
+ * the define #MIPI_SYST_CONFORMANCE_LEVEL.\r
+ * @{\r
+ */\r
+\r
+#if MIPI_SYST_CONFORMANCE_LEVEL > 10\r
+/**\r
+ * Enable 128-bit origin GUID support.\r
+ */\r
+#define MIPI_SYST_PCFG_ENABLE_ORIGIN_GUID\r
+\r
+/**\r
+ * Enable the API variants that send file:line ID pair location records.\r
+ */\r
+#define MIPI_SYST_PCFG_ENABLE_LOCATION_RECORD\r
+#undef MIPI_SYST_PCFG_ENABLE_LOCATION_RECORD\r
+/**\r
+ * Enable the API variants that send the address of the instrumentation location.\r
+ *\r
+ * This API requires #MIPI_SYST_PCFG_ENABLE_LOCATION_RECORD to be set as well.\r
+ * It uses its own define as it additionally requires the function\r
+ * @ref mipi_syst_return_addr() to be implemented for your platform.\r
+ */\r
+#define MIPI_SYST_PCFG_ENABLE_LOCATION_ADDRESS\r
+#undef MIPI_SYST_PCFG_ENABLE_LOCATION_ADDRESS\r
+/**\r
+ * Enable protocol timestamp.\r
+ *\r
+ * This option adds a timestamp into the SyS-T protocol. This\r
+ * option is used if the SyS-T protocol is not embedded into a hardware\r
+ * timestamped trace protocol like MIPI STP or if the HW timestamp cannot\r
+ * be used for other reasons. Setting this option creates the need to define\r
+ * the macros #MIPI_SYST_PLATFORM_CLOCK and #MIPI_SYST_PLATFORM_FREQ to\r
+ * return a 64-bit clock tick value and its frequency.\r
+ */\r
+#define MIPI_SYST_PCFG_ENABLE_TIMESTAMP\r
+\r
+#if defined(_DOXYGEN_) /* only for doxygen, remove the #if to enable */\r
+ /**\r
+ * Enable generation of length field\r
+ *\r
+ * Set this define if the message data shall include the optional length\r
+ * field that indicates how many payload bytes follow.\r
+ */\r
+#define MIPI_SYST_PCFG_LENGTH_FIELD\r
+#endif\r
+\r
+#endif\r
+\r
+#if MIPI_SYST_CONFORMANCE_LEVEL > 20\r
+/**\r
+ * Enable message data CRC32 generation.\r
+ */\r
+#define MIPI_SYST_PCFG_ENABLE_CHECKSUM\r
+\r
+#endif /* #if MIPI_SYST_CONFORMANCE_LEVEL */\r
+\r
+/** @} */\r
+\r
+#include "Platform.h"\r
+#endif\r
+#ifdef __cplusplus\r
+extern "C" {\r
+#endif\r
+\r
+#if defined(MIPI_SYST_PCFG_ENABLE_INLINE)\r
+#define MIPI_SYST_INLINE static MIPI_SYST_CC_INLINE\r
+#else\r
+#define MIPI_SYST_INLINE MIPI_SYST_EXPORT\r
+#endif\r
+\r
+/** SyS-T global state structure.\r
+ * This structure is holding the global SyS-T library state\r
+ */\r
+struct mipi_syst_header {\r
+ mipi_syst_u32 systh_version; /**< SyS-T version ID */\r
+\r
+#if defined(MIPI_SYST_PCFG_ENABLE_PLATFORM_HANDLE_DATA)\r
+ mipi_syst_inithandle_hook_t systh_inith; /**< handle init hook function*/\r
+ mipi_syst_releasehandle_hook_t systh_releaseh; /**< handle release hook */\r
+#endif\r
+\r
+#if MIPI_SYST_CONFORMANCE_LEVEL > 10\r
+ mipi_syst_msg_write_t systh_writer; /**< message output routine */\r
+#endif\r
+#if defined(MIPI_SYST_PCFG_ENABLE_PLATFORM_STATE_DATA)\r
+ struct mipi_syst_platform_state systh_platform;\r
+ /**< platform specific state */\r
+#endif\r
+};\r
+\r
+/**\r
+ * Message data header tag definition\r
+ *\r
+ * Each SyS-T message starts with a 32-bit message tag. The tag defines the\r
+ * message originator and decoding information for the data following\r
+ * the tag.\r
+ */\r
+\r
+struct mipi_syst_msg_tag {\r
+#if defined(MIPI_SYST_BIG_ENDIAN)\r
+ mipi_syst_u32 et_res31 : 1; /**< reserved for future use */\r
+ mipi_syst_u32 et_res30 : 1; /**< reserved for future use */\r
+ mipi_syst_u32 et_subtype : 6; /**< type dependent sub category */\r
+ mipi_syst_u32 et_guid : 1; /**< 128-bit GUID present */\r
+ mipi_syst_u32 et_modunit : 11; /**< unit for GUID or module:unit */\r
+ mipi_syst_u32 et_timestamp : 1;/**< indicate 64-bit timestamp */\r
+ mipi_syst_u32 et_chksum : 1; /**< indicate 32-bit CRC */\r
+ mipi_syst_u32 et_length : 1; /**< indicate length field */\r
+ mipi_syst_u32 et_location : 1; /**< indicate location information */\r
+ mipi_syst_u32 et_res7 : 1; /**< reserved for future use */\r
+ mipi_syst_u32 et_severity : 3; /**< severity level of message */\r
+ mipi_syst_u32 et_type : 4; /**< SyS-T message type ID */\r
+#else\r
+ mipi_syst_u32 et_type : 4; /**< SyS-T message type ID */\r
+ mipi_syst_u32 et_severity : 3; /**< severity level of message */\r
+ mipi_syst_u32 et_res7 : 1; /**< reserved for future use */\r
+ mipi_syst_u32 et_location : 1; /**< indicate location information */\r
+ mipi_syst_u32 et_length : 1; /**< indicate length field */\r
+ mipi_syst_u32 et_chksum : 1; /**< indicate 32-bit CRC */\r
+ mipi_syst_u32 et_timestamp : 1;/**< indicate 64-bit timestamp */\r
+ mipi_syst_u32 et_modunit : 11; /**< unit for GUID or module:unit */\r
+ mipi_syst_u32 et_guid : 1; /**< 128-bit GUID present */\r
+ mipi_syst_u32 et_subtype : 6; /**< type dependent sub category */\r
+ mipi_syst_u32 et_res30 : 1; /**< reserved for future use */\r
+ mipi_syst_u32 et_res31 : 1; /**< reserved for future use */\r
+#endif\r
+};\r
+#define _MIPI_SYST_MK_MODUNIT_ORIGIN(m,u) (((u) & 0xF)|(m<<4))\r
+\r
+/**\r
+ * Message severity level enumeration\r
+ */\r
+enum mipi_syst_severity {\r
+ MIPI_SYST_SEVERITY_MAX = 0, /**< no assigned severity */\r
+ MIPI_SYST_SEVERITY_FATAL = 1, /**< critical error level */\r
+ MIPI_SYST_SEVERITY_ERROR = 2, /**< error message level */\r
+ MIPI_SYST_SEVERITY_WARNING = 3,/**< warning message level */\r
+ MIPI_SYST_SEVERITY_INFO = 4, /**< information message level */\r
+ MIPI_SYST_SEVERITY_USER1 = 5, /**< user defined level 5 */\r
+ MIPI_SYST_SEVERITY_USER2 = 6, /**< user defined level 6 */\r
+ MIPI_SYST_SEVERITY_DEBUG = 7 /**< debug information level */\r
+};\r
+\r
+/**\r
+ * Location information inside a message (64-bit format)\r
+ * Location is either the source position of the instrumentation call, or\r
+ * the call instruction pointer value.\r
+ */\r
+union mipi_syst_msglocation32 {\r
+ struct {\r
+#if defined(MIPI_SYST_BIG_ENDIAN)\r
+ mipi_syst_u16 etls_lineNo; /**< line number in file */\r
+ mipi_syst_u16 etls_fileID; /**< ID of instrumented file */\r
+#else\r
+ mipi_syst_u16 etls_fileID; /**< ID of instrumented file */\r
+ mipi_syst_u16 etls_lineNo; /**< line number in file */\r
+#endif\r
+ } etls_source_location;\r
+\r
+ mipi_syst_u32 etls_code_location:32; /**< instruction pointer value */\r
+};\r
+\r
+/**\r
+ * Location information inside a message (32-bit format)\r
+ * Location is either the source position of the instrumentation call, or\r
+ * the call instruction pointer value.\r
+ */\r
+union mipi_syst_msglocation64 {\r
+ struct {\r
+#if defined(MIPI_SYST_BIG_ENDIAN)\r
+ mipi_syst_u32 etls_lineNo; /**< line number in file */\r
+ mipi_syst_u32 etls_fileID; /**< ID of instrumented file */\r
+#else\r
+ mipi_syst_u32 etls_fileID; /**< ID of instrumented file */\r
+ mipi_syst_u32 etls_lineNo; /**< line number in file */\r
+#endif\r
+ } etls_source_location;\r
+ mipi_syst_u64 etls_code_location; /**< instruction pointer value */\r
+};\r
+\r
+/**\r
+ * Location information record descriptor\r
+ */\r
+struct mipi_syst_msglocation {\r
+ /** Message format\r
+ * 0 = 16-Bit file and 16-Bit line (total: 32-bit)\r
+ * 1 = 32-Bit file and 32-Bit line (total: 64-bit)\r
+ * 2 = 32-bit code address\r
+ * 3 = 64-bit code address\r
+ */\r
+ mipi_syst_u8 el_format;\r
+ union {\r
+ union mipi_syst_msglocation32 loc32; /**< data for 32-bit variant */\r
+ union mipi_syst_msglocation64 loc64; /**< data for 64-bit variant */\r
+ } el_u;\r
+};\r
+\r
+/** internal handle state flags\r
+ */\r
+struct mipi_syst_handle_flags {\r
+ mipi_syst_u32 shf_alloc:1; /**< set to 1 if heap allocated handle */\r
+};\r
+\r
+/** SyS-T connection handle state structure\r
+ *\r
+ * This structure connects the instrumentation API with the underlying SyS-T\r
+ * infrastructure. It plays a similar role to a FILE * in traditional\r
+ * C file IO.\r
+ */\r
+ struct mipi_syst_handle {\r
+ struct mipi_syst_header* systh_header; /**< global state */\r
+ struct mipi_syst_handle_flags systh_flags; /**< handle state */\r
+ struct mipi_syst_msg_tag systh_tag; /**< tag flags */\r
+\r
+#if defined(MIPI_SYST_PCFG_ENABLE_ORIGIN_GUID)\r
+ struct mipi_syst_guid systh_guid; /**< module GUID */\r
+#endif\r
+\r
+#if defined(MIPI_SYST_PCFG_ENABLE_LOCATION_RECORD)\r
+ struct mipi_syst_msglocation systh_location; /**< location record */\r
+#endif\r
+\r
+ mipi_syst_u32 systh_param_count; /**< number of parameters */\r
+ mipi_syst_u32 systh_param[6]; /**< catalog msg parameters */\r
+\r
+#if defined(MIPI_SYST_PCFG_ENABLE_PLATFORM_HANDLE_DATA)\r
+ struct mipi_syst_platform_handle systh_platform;\r
+ /**< platform specific state */\r
+#endif\r
+};\r
+\r
+\r
+#ifdef __cplusplus\r
+} /* extern C */\r
+#endif\r
+#ifndef MIPI_SYST_API_INCLUDED\r
+#include "mipi_syst/api.h"\r
+#endif\r
+\r
+typedef struct mipi_syst_header MIPI_SYST_HEADER;\r
+typedef struct mipi_syst_handle MIPI_SYST_HANDLE;\r
+typedef enum mipi_syst_severity MIPI_SYST_SEVERITY;\r
+typedef struct mipi_syst_guid MIPI_SYST_GUID;\r
+typedef struct mipi_syst_msg_tag MIPI_SYST_MSG_TAG;\r
+typedef struct mipi_syst_handle_flags MIPI_SYST_HANDLE_FLAGS;\r
+#endif\r
projects / ovmf.git / commitdiff