1/* 2Copyright (c) 2018, MIPI Alliance, Inc. 3All rights reserved. 4 5Redistribution and use in source and binary forms, with or without 6modification, are permitted provided that the following conditions 7are met: 8 9* Redistributions of source code must retain the above copyright 10 notice, this list of conditions and the following disclaimer. 11 12* Redistributions in binary form must reproduce the above copyright 13 notice, this list of conditions and the following disclaimer in 14 the documentation and/or other materials provided with the 15 distribution. 16 17* Neither the name of the copyright holder nor the names of its 18 contributors may be used to endorse or promote products derived 19 from this software without specific prior written permission. 20 21THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 22"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 23LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 24A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 25OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 26SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 27LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 31OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32*/ 33 34/* 35 * Contributors: 36 * Norbert Schulz (Intel Corporation) - Initial API and implementation 37 */ 38 39#ifndef MIPI_SYST_H_INCLUDED 40#define MIPI_SYST_H_INCLUDED 41 42/* SyS-T API version information 43 */ 44#define MIPI_SYST_VERSION_MAJOR @SYST_CFG_VERSION_MAJOR@ /**< Major version, incremented if API changes */ 45#define MIPI_SYST_VERSION_MINOR @SYST_CFG_VERSION_MINOR@ /**< Minor version, incremented on compatible extensions */ 46#define MIPI_SYST_VERSION_PATCH @SYST_CFG_VERSION_PATCH@ /**< Patch for existing major, minor, usually 0 */ 47 48/** Define SyS-T API conformance level 49 * 50 * 10 = minimal (only short events) 51 * 20 = low overhead (exluding varag functions and CRC32) 52 * 30 = full implementation 53 */ 54#define MIPI_SYST_CONFORMANCE_LEVEL @SYST_CFG_CONFORMANCE_LEVEL@ 55 56/** Compute SYS-T version value 57 * 58 * Used to compare SYS-T Major.Minor.patch versions numerically at runtime. 59 * 60 * @param ma major version number 61 * @param mi minor version number 62 * @param p patch version number 63 * 64 * Example: 65 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} 66 * 67 * #if MIPI_SYST_VERSION_CODE >= MIPI_SYST_MAKE_VERSION_CODE(1,5,0) 68 * // do what only >= 1.5.x supports 69 * #endif 70 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 71 */ 72#define MIPI_SYST_MAKE_VERSION_CODE(ma, mi, p) (((ma) << 16) | ((mi)<<8) | (p)) 73 74/** Numeric SYS-T version code */ 75#define MIPI_SYST_VERSION_CODE MIPI_SYST_MAKE_VERSION_CODE(\ 76 MIPI_SYST_VERSION_MAJOR,\ 77 MIPI_SYST_VERSION_MINOR,\ 78 MIPI_SYST_VERSION_PATCH) 79 80/* Macros to trick numeric values like __LINE__ into a string 81 */ 82#define _MIPI_SYST_STRINGIFY(x) #x 83#define _MIPI_SYST_CPP_TOSTR(x) _MIPI_SYST_STRINGIFY(x) 84 85#define _MIPI_SYST_VERSION_STRING(a, b, c)\ 86 _MIPI_SYST_CPP_TOSTR(a)"."_MIPI_SYST_CPP_TOSTR(b)"."_MIPI_SYST_CPP_TOSTR(c) 87 88/** Textual version string */ 89#define MIPI_SYST_VERSION_STRING \ 90 _MIPI_SYST_VERSION_STRING(\ 91 MIPI_SYST_VERSION_MAJOR,\ 92 MIPI_SYST_VERSION_MINOR,\ 93 MIPI_SYST_VERSION_PATCH) 94 95#ifndef MIPI_SYST_COMPILER_INCLUDED 96#include "mipi_syst/compiler.h" 97#endif 98 99/* String hash macros for compile time computation of catalog ID's. 100 * Notes: 101 * These macros will only be used with optimized builds, otherwise 102 * a lot of runtime code will be generated. 103 * 104 * Only the last 64 bytes of the string are considered for hashing 105 */ 106#define _MIPI_SYST_HASH1(s,i,x,l) (x*65599u+(mipi_syst_u8)s[(i)<(l)?((l)-1-(i)):(l)]) 107#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) 108#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) 109#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) 110 111#define _MIPI_SYST_HASH_x65599(s,l) ((mipi_syst_u32)_MIPI_SYST_HASH64(s,0,0,l)) 112 113#define _MIPI_SYST_HASH_AT_CPP_TIME(str, offset) (_MIPI_SYST_HASH_x65599(str, sizeof(str)-1) + (offset)) 114#define _MIPI_SYST_HASH_AT_RUN_TIME(str, offset) (mipi_syst_hash_x65599(str, sizeof(str)-1) + (offset)) 115 116#if defined(_MIPI_SYST_OPTIMIZER_ON) 117#define MIPI_SYST_HASH(a, b) _MIPI_SYST_HASH_AT_CPP_TIME((a), (b)) 118#else 119#define MIPI_SYST_HASH(a, b) _MIPI_SYST_HASH_AT_RUN_TIME((a),(b)) 120#endif 121 122#if defined(__cplusplus) 123extern "C" { 124#endif 125 126/** Major Message Types 127 */ 128enum mipi_syst_msgtype { 129 MIPI_SYST_TYPE_BUILD = 0, /**< client build id message */ 130 MIPI_SYST_TYPE_SHORT32 = 1, /**< value only message */ 131 MIPI_SYST_TYPE_STRING = 2, /**< text message output */ 132 MIPI_SYST_TYPE_CATALOG = 3, /**< catalog message output */ 133 MIPI_SYST_TYPE_RAW = 6, /**< raw binary data */ 134 MIPI_SYST_TYPE_SHORT64 = 7, /**< value only message */ 135 MIPI_SYST_TYPE_CLOCK = 8, /**< clock sync message */ 136 137 MIPI_SYST_TYPE_MAX 138}; 139 140/** MIPI_SYST_TYPE_DEBUG_STRING Sub-Types 141 */ 142enum mipi_syst_subtype_string { 143 MIPI_SYST_STRING_GENERIC = 1, /**< string generic debug */ 144 MIPI_SYST_STRING_FUNCTIONENTER = 2, /**< string is function name */ 145 MIPI_SYST_STRING_FUNCTIONEXIT = 3, /**< string is function name */ 146 MIPI_SYST_STRING_INVALIDPARAM = 5, /**< invalid SyS-T APIcall */ 147 MIPI_SYST_STRING_ASSERT = 7, /**< Software Assert: failure */ 148 MIPI_SYST_STRING_PRINTF_32 = 11, /**< printf with 32-bit packing */ 149 MIPI_SYST_STRING_PRINTF_64 = 12, /**< printf with 64-bit packing */ 150 151 MIPI_SYST_STRING_MAX 152}; 153 154/** MIPI_SYST_TYPE_CATALOG Sub-Types 155 */ 156enum mipi_syst_subtype_catalog { 157 MIPI_SYST_CATALOG_ID32_P32 = 1, /**< 32-bit catalog ID, 32-bit packing */ 158 MIPI_SYST_CATALOG_ID64_P32 = 2, /**< 64-bit catalog ID, 32-bit packing */ 159 MIPI_SYST_CATALOG_ID32_P64 = 5, /**< 32-bit catalog ID, 64-bit packing */ 160 MIPI_SYST_CATALOG_ID64_P64 = 6, /**< 64-bit catalog ID, 64-bit packing */ 161 162 MIPI_SYST_CATALOG_MAX 163}; 164 165/** MIPI_SYST_TYPE_CLOCK Sub-Types 166 */ 167enum mipi_syst_subtype_clock{ 168 MIPI_SYST_CLOCK_TRANSPORT_SYNC = 1, /**< SyS-T clock & frequency sync */ 169 MIPI_SYST_CLOCK_MAX 170}; 171 172enum mipi_syst_subtype_build { 173 MIPI_SYST_BUILD_ID_COMPACT32 = 0, /**< compact32 build id */ 174 MIPI_SYST_BUILD_ID_COMPACT64 = 1, /**< compact64 build id */ 175 MIPI_SYST_BUILD_ID_LONG = 2, /**< normal build message */ 176 MIPI_SYST_BUILD_MAX 177}; 178 179struct mipi_syst_header; 180struct mipi_syst_handle; 181struct mipi_syst_scatter_prog; 182 183/** 128-bit GUID style message origin ID */ 184struct mipi_syst_guid { 185 union { 186 mipi_syst_u8 b[16]; 187 mipi_syst_u64 ll[2]; 188 } u; 189}; 190 191/** GUID initializer code 192 * 193 * This macro simplifies converting a GUID from its string representation 194 * into the mipi_syst_guid data structure. The following example shows 195 * how the values from a GUID string are used with the macro. Each numeric 196 * component from the GUID string gets converted into a hex value parameter 197 * when invoking the macro. 198 * 199 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} 200 * 201 * // Guid: f614b99d-99a1-4c04-8c30-90999ab5fe05 202 * 203 * struct mipi_syst_guid guid = 204 * MIPI_SYST_GEN_GUID(0xf614b99d, 0x99a1, 0x4c04, 0x8c30, 0x90999ab5fe05); 205 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 206 */ 207#define MIPI_SYST_GEN_GUID(l1, w1, w2, w3, l2) \ 208 {{\ 209 (mipi_syst_u8)((mipi_syst_u32)(l1) >> 24), \ 210 (mipi_syst_u8)((mipi_syst_u32)(l1) >> 16), \ 211 (mipi_syst_u8)((mipi_syst_u32)(l1) >> 8), \ 212 (mipi_syst_u8)((mipi_syst_u32)(l1) >> 0), \ 213 (mipi_syst_u8)((mipi_syst_u16)(w1) >> 8), \ 214 (mipi_syst_u8)((mipi_syst_u16)(w1) >> 0), \ 215 (mipi_syst_u8)((mipi_syst_u16)(w2) >> 8), \ 216 (mipi_syst_u8)((mipi_syst_u16)(w2) >> 0), \ 217 (mipi_syst_u8)((mipi_syst_u16)(w3) >> 8), \ 218 (mipi_syst_u8)((mipi_syst_u16)(w3) >> 0), \ 219 (mipi_syst_u8)((mipi_syst_u64)(l2) >> 40), \ 220 (mipi_syst_u8)((mipi_syst_u64)(l2) >> 32), \ 221 (mipi_syst_u8)((mipi_syst_u64)(l2) >> 24), \ 222 (mipi_syst_u8)((mipi_syst_u64)(l2) >> 16), \ 223 (mipi_syst_u8)((mipi_syst_u64)(l2) >> 8), \ 224 (mipi_syst_u8)((mipi_syst_u64)(l2) >> 0) \ 225 }} 226 227 /** SyS-T client origin data 228 * 229 * This structure holds the GUID or header origin and unit data 230 * used by SyS-T handles. The structure gets passed into the handle 231 * creation functions to initialize the values that identify clients. 232 * @see MIPI_SYST_SET_HANDLE_GUID_UNIT 233 * @see MIPI_SYST_SET_HANDLE_MODULE_UNIT 234 * @see MIPI_SYST_SET_HANDLE_ORIGIN 235 */ 236struct mipi_syst_origin { 237 struct mipi_syst_guid guid; /**< origin GUID or module value */ 238 mipi_syst_u16 unit; /**< unit value */ 239}; 240 241/** Origin structure initializer code using GUID 242* 243* This macro simplifies initializing a mipi_syst_origin structure. The 244* first 5 parameters are GUID values as used by the MIPI_SYST_GEN_GUID 245* macro. The last parameter is the unit value (11-Bits). 246* @see MIPI_SYST_GEN_GUID 247* 248* 249* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} 250* 251* // Guid: {494E5443-B659-45AF-B786-9DB0786248AE} 252 253* 254* struct mipi_syst_origin = origin 255* MIPI_SYST_GEN_ORIGIN_GUID( 256* 0x494E5443, 0xB659, 0x45AF, 0xB786, 0x9DB0786248AE, 257* 0x1); 258* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 259*/ 260#define MIPI_SYST_GEN_ORIGIN_GUID(l1, w1, w2, w3, l2 , u) \ 261 {\ 262 MIPI_SYST_GEN_GUID(l1, w1, w2, w3, l2) ,\ 263 u\ 264 } 265 266/** Origin structure initializer code using header module value 267* 268* This macro simplifies initializing a mipi_syst_origin structure. The 269* first parameter is the header origin value (7-Bits). The second parameter 270* is the unit value (4-bits) 271* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} 272* 273* // Guid: {494E5443-B659-45AF-B786-9DB0786248AE} 274 275* #define MODULE_X 0x10 276* struct mipi_syst_origin = 277* MIPI_SYST_GEN_ORIGIN_MODULE(MODULE_X, 0x1); 278* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 279*/ 280#define MIPI_SYST_GEN_ORIGIN_MODULE(m , u) \ 281 {\ 282 MIPI_SYST_GEN_GUID(0,0,0, ((mipi_syst_u16)(m & 0x7F)) << 8, 0 ),\ 283 u\ 284 } 285/** 286 * Global state initialization hook definition 287 * 288 * This function gets called in the context of the mipi_syst_init() API 289 * function after the generic state members of the global state 290 * structure syst_hdr have been setup. It's purpose is to initialize the 291 * platform dependent portion of the state and other necessary 292 * platform specific initialization steps. 293 * 294 * @param systh Pointer to global state structure 295 * @param p user defined value or pointer to data 296 * @see mipi_syst_header 297 */ 298typedef void (MIPI_SYST_CALLCONV *mipi_syst_inithook_t)(struct mipi_syst_header *systh, 299 const void *p); 300 301/** 302 * Global state destroy hook definition 303 * 304 * This function gets called in the context of the mipi_syst_destroy() API 305 * function before the generic state members of the global state 306 * structure syst_hdr have been destroyed. Its purpose is to free resources 307 * used by the platform dependent portion of the global state. 308 * 309 * @param systh Pointer to global state structure 310 */ 311typedef void (MIPI_SYST_CALLCONV *mipi_syst_destroyhook_t)(struct mipi_syst_header *systh); 312 313/** 314 * SyS-T handle state initialization hook definition 315 * 316 * This function gets called in the context of IO handle generation. 317 * Its purpose is to initialize the platform dependent portion of 318* the handle and other necessary platform specific initialization steps. 319 * 320 * @param systh Pointer to new SyS-T handle 321 * @see syst_handle_t 322 */ 323typedef void (*mipi_syst_inithandle_hook_t)(struct mipi_syst_handle *systh); 324 325/** 326 * SyS-T handle state release hook definition 327 * 328 * This function gets called when a handle is about to be destroyed.. 329 * Its purpose is to free any resources allocated during the handle 330 * generation. 331 * 332 * @param systh Pointer to handle that is destroyed 333 * @see syst_handle_t 334 */ 335typedef void (*mipi_syst_releasehandle_hook_t)(struct mipi_syst_handle *systh); 336 337/** 338 * Low level message write routine definition 339 * 340 * This function is called at the end of an instrumentation API to output 341 * the raw message data. 342 * 343 * @param systh pointer to a SyS-T handle structure used in the API call, 344 * @param scatterprog pointer to a list of scatter write instructions that 345 * encodes how to convert the descriptor pointer by 346 * pdesc into raw binary data. This list doesn't include 347 * the mandatory first 32 tag byte value pointed by pdesc. 348 * @param pdesc pointer to a message descriptor, which containing at least 349 * the 32-bit message tag data 350 */ 351typedef void (*mipi_syst_msg_write_t)( 352 struct mipi_syst_handle *systh, 353 struct mipi_syst_scatter_prog *scatterprog, 354 const void *pdesc); 355 356#ifdef __cplusplus 357} /* extern C */ 358#endif 359#ifndef MIPI_SYST_PLATFORM_INCLUDED 360 361/** 362 * @defgroup PCFG_Config Platform Feature Configuration Defines 363 * 364 * Defines to customize the SyS-T feature set to match the platform needs. 365 * 366 * Each optional library feature can be disabled by not defining the related 367 * MIPI_SYST_PCFG_ENABLE define. Removing unused features in this way reduces 368 * both memory footprint and runtime overhead of SyS-T. 369 */ 370 371/** 372 * @defgroup PCFG_Global Platform Wide Configuration 373 * @ingroup PCFG_Config 374 * 375 * These defines enable global features in the SyS-T library. 376 * @{ 377 */ 378 379 380 /** 381 * Extend Platform global SyS-T data state 382 * 383 * This define extends the global SyS-T state data structure 384 * mipi_syst_header with platform private content. A platform typically 385 * stores data for SyS-T handle creation processing in this structure. 386 * 387 * Note: This data is not touched by the library code itself, but typically 388 * is used by platform hook functions for handle creation and destruction. 389 * **These hook function calls are not lock protected and may happen 390 * concurrently!** The hook functions need to implement locking if they 391 * modify the platform state data. 392 * 393 * The platform example uses #mipi_syst_platform_state as data state extension. 394 */ 395#define MIPI_SYST_PCFG_ENABLE_PLATFORM_STATE_DATA 396 397/** 398 * Extend SyS-T handle data state 399 * 400 * This define extends the SyS-T handle state data structure 401 * mipi_syst_handle with platform private content. A platform typically 402 * stores data for fast trace hardware access in the handle data, for 403 * example a volatile pointer to an MMIO space. 404 * 405 * The platform example uses #mipi_syst_platform_handle as handle state 406 * extension. 407 */ 408#define MIPI_SYST_PCFG_ENABLE_PLATFORM_HANDLE_DATA 409 410/** 411 * Enable HEAP usage for handle generation 412 * 413 * This macro tells the SyS-T library to enable the heap allocation handle 414 * creation API #MIPI_SYST_ALLOC_HANDLE. 415 * The platform must provide the macros #MIPI_SYST_HEAP_MALLOC and 416 * #MIPI_SYST_HEAP_FREE to point SyS-T to the platform malloc and free 417 * functions. 418 * 419 * Note: In OS kernel space environments, you must use unpaged memory 420 * allocation functions. 421 */ 422#define MIPI_SYST_PCFG_ENABLE_HEAP_MEMORY 423 424/* MSVC and GNU compiler 64-bit mode */ 425 426/** 427 * Enable 64-bit instruction addresses 428 * 429 * Set this define if running in 64-bit code address space. 430 */ 431#if defined(_WIN64) || defined(__x86_64__) || defined (__LP64__) 432#define MIPI_SYST_PCFG_ENABLE_64BIT_ADDR 433#endif 434/** 435 * Enable atomic 64-bit write operations 436 * 437 * Set this define if your platform supports an atomic 64-bit data write 438 * operation. This results in fewer MMIO accesses.The SyS-T library 439 * defaults to 2 consecutive 32-Bit writes otherwise. 440 */ 441#if defined(_WIN64) || defined(__x86_64__) || defined (__LP64__) 442#define MIPI_SYST_PCFG_ENABLE_64BIT_IO 443#endif 444 445/** 446 * Enable helper function code inlining 447 * 448 * Set this define if speed is more important than code size on your platform. 449 * It causes several helper function to get inlined, producing faster, but 450 * also larger, code. 451 */ 452#define MIPI_SYST_PCFG_ENABLE_INLINE 453 454/** @} */ 455 456/** 457 * @defgroup PCFG_ApiSet Supported API sets 458 * @ingroup PCFG_Config 459 * 460 * These defines enable API sets in the SyS-T library. They are set by default 461 * depending on the SyS-T API conformance level. The level is specified using 462 * the define #MIPI_SYST_CONFORMANCE_LEVEL. 463 * @{ 464 */ 465 466#if MIPI_SYST_CONFORMANCE_LEVEL > 10 467 /** 468 * Use SyS-T scatter write output function 469 * 470 * The library comes with an output routine that is intended to write data out 471 * to an MMIO space. It simplifies a SyS-T platform integration as 472 * only low-level access macros must be provided for outputting data. These 473 * macros follow MIPI System Trace Protocol (STP) naming convention, also 474 * non STP generators can use this interface. 475 * 476 * These low level output macros are: 477 * 478 * #MIPI_SYST_OUTPUT_D32MTS, #MIPI_SYST_OUTPUT_D64MTS, 479 * #MIPI_SYST_OUTPUT_D32TS, #MIPI_SYST_OUTPUT_D64, 480 * #MIPI_SYST_OUTPUT_D32, #MIPI_SYST_OUTPUT_D16, #MIPI_SYST_OUTPUT_D8 and 481 * #MIPI_SYST_OUTPUT_FLAG 482 * 483 * Note: This version of the write function always starts messages 484 * using a 32-bit timestamped record also other sized timestamped 485 * packets are allowed by the SyS-T specification. 486 */ 487#define MIPI_SYST_PCFG_ENABLE_DEFAULT_SCATTER_WRITE 488 489/** 490 * Enable the Catalog API for 32-Bit Catalog IDs. 491 */ 492#define MIPI_SYST_PCFG_ENABLE_CATID32_API 493 494/** 495 * Enable the Catalog API for 64-Bit Catalog IDs. 496 */ 497#define MIPI_SYST_PCFG_ENABLE_CATID64_API 498 499/** 500 * Enable plain UTF-8 string output APIs. 501 */ 502#define MIPI_SYST_PCFG_ENABLE_STRING_API 503 504/** 505 * Enable raw data output APIs 506 */ 507#define MIPI_SYST_PCFG_ENABLE_WRITE_API 508 509/** 510 * Enable Build API 511 */ 512#define MIPI_SYST_PCFG_ENABLE_BUILD_API 513#endif /* MIPI_SYST_CONFORMANCE_LEVEL > 10 */ 514 515#if MIPI_SYST_CONFORMANCE_LEVEL > 20 516 /** 517 * Enable printf API support 518 * 519 * Note: 520 * Enabling printf requires compiler var_arg support as defined by the 521 * header files stdarg.h stddef.h. 522 */ 523 524#define MIPI_SYST_PCFG_ENABLE_PRINTF_API 525 526/** 527 * Maximum size of printf payload in bytes. 528 * Adjust this value if larger strings shall be supported by the library. 529 * The buffer space is located in stack memory when calling one of the printf 530 * style APIs. 531 */ 532#define MIPI_SYST_PCFG_PRINTF_ARGBUF_SIZE 1024 533 534#endif /* #if MIPI_SYST_CONFORMANCE_LEVEL > 20 */ 535 536/* @} */ 537 538/** 539 * @defgroup PCFG_Message Optional Message Attributes 540 * @ingroup PCFG_Config 541 * 542 * These defines enable optional message components. They are set by default 543 * depending on the SyS-T API conformance level. The level is specified using 544 * the define #MIPI_SYST_CONFORMANCE_LEVEL. 545 * @{ 546 */ 547 548#if MIPI_SYST_CONFORMANCE_LEVEL > 10 549/** 550 * Enable 128-bit origin GUID support. 551 */ 552#define MIPI_SYST_PCFG_ENABLE_ORIGIN_GUID 553 554/** 555 * Enable the API variants that send file:line ID pair location records. 556 */ 557#define MIPI_SYST_PCFG_ENABLE_LOCATION_RECORD 558 559/** 560 * Enable the API variants that send the address of the instrumentation location. 561 * 562 * This API requires #MIPI_SYST_PCFG_ENABLE_LOCATION_RECORD to be set as well. 563 * It uses its own define as it additionally requires the function 564 * @ref mipi_syst_return_addr() to be implemented for your platform. 565 */ 566#define MIPI_SYST_PCFG_ENABLE_LOCATION_ADDRESS 567 568/** 569 * Enable protocol timestamp. 570 * 571 * This option adds a timestamp into the SyS-T protocol. This 572 * option is used if the SyS-T protocol is not embedded into a hardware 573 * timestamped trace protocol like MIPI STP or if the HW timestamp cannot 574 * be used for other reasons. Setting this option creates the need to define 575 * the macros #MIPI_SYST_PLATFORM_CLOCK and #MIPI_SYST_PLATFORM_FREQ to 576 * return a 64-bit clock tick value and its frequency. 577 */ 578#define MIPI_SYST_PCFG_ENABLE_TIMESTAMP 579 580 /** 581 * Enable generation of length field 582 * 583 * Set this define if the message data shall include the optional length 584 * field that indicates how many payload bytes follow. 585 */ 586#define MIPI_SYST_PCFG_LENGTH_FIELD 587 588#endif 589 590#if MIPI_SYST_CONFORMANCE_LEVEL > 20 591/** 592 * Enable message data CRC32 generation. 593 */ 594#define MIPI_SYST_PCFG_ENABLE_CHECKSUM 595 596#endif /* #if MIPI_SYST_CONFORMANCE_LEVEL */ 597 598/** @} */ 599 600#include "mipi_syst/platform.h" 601#endif 602#ifdef __cplusplus 603extern "C" { 604#endif 605 606#if defined(MIPI_SYST_PCFG_ENABLE_INLINE) 607#define MIPI_SYST_INLINE static MIPI_SYST_CC_INLINE 608#else 609#define MIPI_SYST_INLINE MIPI_SYST_EXPORT 610#endif 611 612/** SyS-T global state structure. 613 * This structure is holding the global SyS-T library state 614 */ 615struct mipi_syst_header { 616 mipi_syst_u32 systh_version; /**< SyS-T version ID */ 617 618#if defined(MIPI_SYST_PCFG_ENABLE_PLATFORM_HANDLE_DATA) 619 mipi_syst_inithandle_hook_t systh_inith; /**< handle init hook function*/ 620 mipi_syst_releasehandle_hook_t systh_releaseh; /**< handle release hook */ 621#endif 622 623#if MIPI_SYST_CONFORMANCE_LEVEL > 10 624 mipi_syst_msg_write_t systh_writer; /**< message output routine */ 625#endif 626#if defined(MIPI_SYST_PCFG_ENABLE_PLATFORM_STATE_DATA) 627 struct mipi_syst_platform_state systh_platform; 628 /**< platform specific state */ 629#endif 630}; 631 632/** 633 * Message data header tag definition 634 * 635 * Each SyS-T message starts with a 32-bit message tag. The tag defines the 636 * message originator and decoding information for the data following 637 * the tag. 638 */ 639 640struct mipi_syst_msg_tag { 641#if defined(MIPI_SYST_BIG_ENDIAN) 642 mipi_syst_u32 et_res31 : 1; /**< reserved for future use */ 643 mipi_syst_u32 et_res30 : 1; /**< reserved for future use */ 644 mipi_syst_u32 et_subtype : 6; /**< type dependent sub category */ 645 mipi_syst_u32 et_guid : 1; /**< 128-bit GUID present */ 646 mipi_syst_u32 et_modunit : 11; /**< unit for GUID or module:unit */ 647 mipi_syst_u32 et_timestamp : 1;/**< indicate 64-bit timestamp */ 648 mipi_syst_u32 et_chksum : 1; /**< indicate 32-bit CRC */ 649 mipi_syst_u32 et_length : 1; /**< indicate length field */ 650 mipi_syst_u32 et_location : 1; /**< indicate location information */ 651 mipi_syst_u32 et_res7 : 1; /**< reserved for future use */ 652 mipi_syst_u32 et_severity : 3; /**< severity level of message */ 653 mipi_syst_u32 et_type : 4; /**< SyS-T message type ID */ 654#else 655 mipi_syst_u32 et_type : 4; /**< SyS-T message type ID */ 656 mipi_syst_u32 et_severity : 3; /**< severity level of message */ 657 mipi_syst_u32 et_res7 : 1; /**< reserved for future use */ 658 mipi_syst_u32 et_location : 1; /**< indicate location information */ 659 mipi_syst_u32 et_length : 1; /**< indicate length field */ 660 mipi_syst_u32 et_chksum : 1; /**< indicate 32-bit CRC */ 661 mipi_syst_u32 et_timestamp : 1;/**< indicate 64-bit timestamp */ 662 mipi_syst_u32 et_modunit : 11; /**< unit for GUID or module:unit */ 663 mipi_syst_u32 et_guid : 1; /**< 128-bit GUID present */ 664 mipi_syst_u32 et_subtype : 6; /**< type dependent sub category */ 665 mipi_syst_u32 et_res30 : 1; /**< reserved for future use */ 666 mipi_syst_u32 et_res31 : 1; /**< reserved for future use */ 667#endif 668}; 669#define _MIPI_SYST_MK_MODUNIT_ORIGIN(m,u) (((u) & 0xF)|(m<<4)) 670 671/** 672 * Message severity level enumeration 673 */ 674enum mipi_syst_severity { 675 MIPI_SYST_SEVERITY_MAX = 0, /**< no assigned severity */ 676 MIPI_SYST_SEVERITY_FATAL = 1, /**< critical error level */ 677 MIPI_SYST_SEVERITY_ERROR = 2, /**< error message level */ 678 MIPI_SYST_SEVERITY_WARNING = 3,/**< warning message level */ 679 MIPI_SYST_SEVERITY_INFO = 4, /**< information message level */ 680 MIPI_SYST_SEVERITY_USER1 = 5, /**< user defined level 5 */ 681 MIPI_SYST_SEVERITY_USER2 = 6, /**< user defined level 6 */ 682 MIPI_SYST_SEVERITY_DEBUG = 7 /**< debug information level */ 683}; 684 685/** 686 * Location information inside a message (64-bit format) 687 * Location is either the source position of the instrumentation call, or 688 * the call instruction pointer value. 689 */ 690union mipi_syst_msglocation32 { 691 struct { 692#if defined(MIPI_SYST_BIG_ENDIAN) 693 mipi_syst_u16 etls_lineNo; /**< line number in file */ 694 mipi_syst_u16 etls_fileID; /**< ID of instrumented file */ 695#else 696 mipi_syst_u16 etls_fileID; /**< ID of instrumented file */ 697 mipi_syst_u16 etls_lineNo; /**< line number in file */ 698#endif 699 } etls_source_location; 700 701 mipi_syst_u32 etls_code_location:32; /**< instruction pointer value */ 702}; 703 704/** 705 * Location information inside a message (32-bit format) 706 * Location is either the source position of the instrumentation call, or 707 * the call instruction pointer value. 708 */ 709union mipi_syst_msglocation64 { 710 struct { 711#if defined(MIPI_SYST_BIG_ENDIAN) 712 mipi_syst_u32 etls_lineNo; /**< line number in file */ 713 mipi_syst_u32 etls_fileID; /**< ID of instrumented file */ 714#else 715 mipi_syst_u32 etls_fileID; /**< ID of instrumented file */ 716 mipi_syst_u32 etls_lineNo; /**< line number in file */ 717#endif 718 } etls_source_location; 719 mipi_syst_u64 etls_code_location; /**< instruction pointer value */ 720}; 721 722/** 723 * Location information record descriptor 724 */ 725struct mipi_syst_msglocation { 726 /** Message format 727 * 0 = 16-Bit file and 16-Bit line (total: 32-bit) 728 * 1 = 32-Bit file and 32-Bit line (total: 64-bit) 729 * 2 = 32-bit code address 730 * 3 = 64-bit code address 731 */ 732 mipi_syst_u8 el_format; 733 union { 734 union mipi_syst_msglocation32 loc32; /**< data for 32-bit variant */ 735 union mipi_syst_msglocation64 loc64; /**< data for 64-bit variant */ 736 } el_u; 737}; 738 739/** internal handle state flags 740 */ 741struct mipi_syst_handle_flags { 742 mipi_syst_u32 shf_alloc:1; /**< set to 1 if heap allocated handle */ 743}; 744 745/** SyS-T connection handle state structure 746 * 747 * This structure connects the instrumentation API with the underlying SyS-T 748 * infrastructure. It plays a similar role to a FILE * in traditional 749 * C file IO. 750 */ 751 struct mipi_syst_handle { 752 struct mipi_syst_header* systh_header; /**< global state */ 753 struct mipi_syst_handle_flags systh_flags; /**< handle state */ 754 struct mipi_syst_msg_tag systh_tag; /**< tag flags */ 755 756#if defined(MIPI_SYST_PCFG_ENABLE_ORIGIN_GUID) 757 struct mipi_syst_guid systh_guid; /**< module GUID */ 758#endif 759 760#if defined(MIPI_SYST_PCFG_ENABLE_LOCATION_RECORD) 761 struct mipi_syst_msglocation systh_location; /**< location record */ 762#endif 763 764 mipi_syst_u32 systh_param_count; /**< number of parameters */ 765 mipi_syst_u32 systh_param[6]; /**< catalog msg parameters */ 766 767#if defined(MIPI_SYST_PCFG_ENABLE_PLATFORM_HANDLE_DATA) 768 struct mipi_syst_platform_handle systh_platform; 769 /**< platform specific state */ 770#endif 771}; 772 773 774#ifdef __cplusplus 775} /* extern C */ 776#endif 777#ifndef MIPI_SYST_API_INCLUDED 778#include "mipi_syst/api.h" 779#endif 780 781#endif 782
