/* | |
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 1 /**< Major version, incremented if API changes */ | |
#define MIPI_SYST_VERSION_MINOR 0 /**< Minor version, incremented on compatible extensions */ | |
#define MIPI_SYST_VERSION_PATCH 0 /**< 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 30 | |
/** 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 | |
#undef 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 | |
#undef 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 | |
#undef 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 | |
#undef 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 | |
#undef 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 "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 | |
typedef struct mipi_syst_header MIPI_SYST_HEADER; | |
typedef struct mipi_syst_handle MIPI_SYST_HANDLE; | |
typedef enum mipi_syst_severity MIPI_SYST_SEVERITY; | |
typedef struct mipi_syst_guid MIPI_SYST_GUID; | |
typedef struct mipi_syst_msg_tag MIPI_SYST_MSG_TAG; | |
typedef struct mipi_syst_handle_flags MIPI_SYST_HANDLE_FLAGS; | |
#endif |