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