| /******************************************************************************* | |
| * Trace Recorder Library for Tracealyzer v3.0.2 | |
| * Percepio AB, www.percepio.com | |
| * | |
| * trcRecorder.c | |
| * | |
| * Public interface and configurations for the trace recorder library. | |
| * | |
| * Terms of Use | |
| * This software (the "Tracealyzer Recorder Library") is the intellectual | |
| * property of Percepio AB and may not be sold or in other ways commercially | |
| * redistributed without explicit written permission by Percepio AB. | |
| * | |
| * Separate conditions applies for the SEGGER branded source code included. | |
| * | |
| * The recorder library is free for use together with Percepio products. | |
| * You may distribute the recorder library in its original form, but public | |
| * distribution of modified versions require approval by Percepio AB. | |
| * | |
| * Disclaimer | |
| * The trace tool and recorder library is being delivered to you AS IS and | |
| * Percepio AB makes no warranty as to its use or performance. Percepio AB does | |
| * not and cannot warrant the performance or results you may obtain by using the | |
| * software or documentation. Percepio AB make no warranties, express or | |
| * implied, as to noninfringement of third party rights, merchantability, or | |
| * fitness for any particular purpose. In no event will Percepio AB, its | |
| * technology partners, or distributors be liable to you for any consequential, | |
| * incidental or special damages, including any lost profits or lost savings, | |
| * even if a representative of Percepio AB has been advised of the possibility | |
| * of such damages, or for any claim by any third party. Some jurisdictions do | |
| * not allow the exclusion or limitation of incidental, consequential or special | |
| * damages, or the exclusion of implied warranties or limitations on how long an | |
| * implied warranty may last, so the above limitations may not apply to you. | |
| * | |
| * Tabs are used for indent in this file (1 tab = 4 spaces) | |
| * | |
| * Copyright Percepio AB, 2015. | |
| * www.percepio.com | |
| ******************************************************************************/ | |
| #ifndef _TRC_RECORDER_H | |
| #define _TRC_RECORDER_H | |
| #ifdef __cplusplus | |
| extern C { | |
| #endif | |
| #include "trcConfig.h" | |
| #include "trcKernelPort.h" | |
| #include "trcHardwarePort.h" | |
| #if (USE_TRACEALYZER_RECORDER == 1) | |
| /*** User API *****************************************************************/ | |
| /****************************************************************************** | |
| * vTracePrint | |
| * | |
| * Generates "User Events", with unformatted text. | |
| * | |
| * User Events can be used for very efficient application logging, and are shown | |
| * as yellow labels in the main trace view. | |
| * | |
| * You may group User Events into User Event Channels. The yellow User Event | |
| * labels shows the logged string, preceeded by the channel name within | |
| * brackets. For example: | |
| * | |
| * "[MyChannel] Hello World!" | |
| * | |
| * The User Event Channels are shown in the View Filter, which makes it easy to | |
| * select what User Events you wish to display. User Event Channels are created | |
| * using vTraceStoreUserEventChannelName(). | |
| * | |
| * Example: | |
| * | |
| * char* error_uechannel = vTraceStoreUserEventChannelName("Errors"); | |
| * ... | |
| * vTracePrint(error_uechannel, "Shouldn't reach this code!"); | |
| * | |
| ******************************************************************************/ | |
| void vTracePrint(const char* chn, const char* str); | |
| /****************************************************************************** | |
| * vTracePrintF | |
| * | |
| * Generates "User Events", with formatted text and data, similar to a "printf". | |
| * It is very fast since the actual formatting is done on the host side when the | |
| * trace is displayed. | |
| * | |
| * User Events can be used for very efficient application logging, and are shown | |
| * as yellow labels in the main trace view. | |
| * An advantage of User Events is that data can be plotted in the "User Event | |
| * Signal Plot" view, visualizing any data you log as User Events, discrete | |
| * states or control system signals (e.g. system inputs or outputs). | |
| * | |
| * You may group User Events into User Event Channels. The yellow User Event | |
| * labels show the logged string, preceeded by the channel name within brackets. | |
| * | |
| * Example: | |
| * | |
| * "[MyChannel] Hello World!" | |
| * | |
| * The User Event Channels are shown in the View Filter, which makes it easy to | |
| * select what User Events you wish to display. User Event Channels are created | |
| * using vTraceStoreUserEventChannelName(). | |
| * | |
| * Example: | |
| * | |
| * char* adc_uechannel = vTraceStoreUserEventChannelName("ADC User Events"); | |
| * ... | |
| * vTracePrint(adc_uechannel, | |
| * "ADC channel %d: %lf volts", | |
| * ch, (double)adc_reading/(double)scale); | |
| * | |
| * All data arguments are assumed to be 32 bt wide. The following formats are | |
| * supported in v2.8: | |
| * %d - signed integer | |
| * %u - unsigned integer | |
| * %X - hexadecimal (uppercase) | |
| * %x - hexadecimal (lowercase) | |
| * %s - string (currently, this must be an earlier stored symbol name) | |
| * | |
| * Up to 15 data arguments are allowed, with a total size of maximum 60 byte | |
| * including 8 byte for the base event fields and the format string. So with | |
| * one data argument, the maximum string length is 48 chars. If this is exceeded | |
| * the string is truncated (4 bytes at a time). | |
| * | |
| ******************************************************************************/ | |
| void vTracePrintF(const char* chn, const char* fmt, ...); | |
| /******************************************************************************* | |
| * vTraceStoreUserEventChannelName(const char* name) | |
| * | |
| * Parameter name: the channel name to store (const string literal) | |
| * | |
| * Stores a name for a user event channel, returns the handle (just a pointer | |
| * to the provided string). Typically assigned to a "channel" variable that | |
| * keeps it for later calls to vTracePrintF(); | |
| ******************************************************************************/ | |
| char* vTraceStoreUserEventChannelName(const char* name); | |
| /******************************************************************************* | |
| * vTraceStoreKernelObjectName(void* object, const char* name) | |
| * | |
| * Parameter object: pointer to the kernel object that shall be named | |
| * Parameter name: the name to store (const string literal) | |
| * | |
| * Stores a name for kernel objects (Semaphore, Mailbox, etc.). | |
| ******************************************************************************/ | |
| void vTraceStoreKernelObjectName(void* object, const char* name); | |
| /******************************************************************************* | |
| * vTraceSetISRProperties(const char* name, char priority) | |
| * | |
| * Parameter name: the name to give the the ISR, also serves as handle. | |
| * Parameter priority: the priority level of the ISR. | |
| * | |
| * Stores a name and priority level for an Interrupt Service Routine, to allow | |
| * for better visualization. The string address is used as a unique handle. | |
| * | |
| * Example: | |
| * | |
| * vTraceSetISRProperties("ISRTimer1", ISRPriorityTimer1); | |
| * ... | |
| * void ISR_handler() | |
| * { | |
| * vTraceStoreISRBegin("ISRTimer1"); | |
| * ... | |
| * vTraceStoreISREnd(0); | |
| * } | |
| ******************************************************************************/ | |
| void vTraceSetISRProperties(const char* name, char priority); | |
| /******************************************************************************* | |
| * vTraceStoreISRBegin(void* handle); | |
| * | |
| * Parameter handle: ID of the ISR, which is "name" in vTraceSetISRProperties | |
| * | |
| * Registers the beginning of an Interrupt Service Routine (ISR), i.e., or an | |
| * exception handler. | |
| * | |
| * Example: | |
| * | |
| * vTraceSetISRProperties("ISRTimer1", ISRPriorityTimer1); | |
| * ... | |
| * void ISR_handler() | |
| * { | |
| * vTraceStoreISRBegin("ISRTimer1"); | |
| * ... | |
| * vTraceStoreISREnd(0); | |
| * } | |
| ******************************************************************************/ | |
| void vTraceStoreISRBegin(void* handle); | |
| /******************************************************************************* | |
| * vTraceStoreISREnd | |
| * | |
| * Registers the end of an Interrupt Service Routine. | |
| * | |
| * This function attempts to automatically detect if a task switch will take | |
| * place when interrupt ends. If this is possible depends on the kernel port. | |
| * | |
| * Example: | |
| * #define PRIO_ISR_TIMER1 3 // the hardware priority of the interrupt | |
| * ... | |
| * vTraceSetISRProperties("ISRTimer1", PRIO_ISR_TIMER1); | |
| * ... | |
| * void ISR_handler() | |
| * { | |
| * vTraceStoreISRBegin("ISRTimer1"); | |
| * ... | |
| * vTraceStoreISREnd(); | |
| * } | |
| * | |
| ******************************************************************************/ | |
| void vTraceStoreISREnd(void); | |
| /******************************************************************************* | |
| * vTraceStoreISREndManual | |
| * | |
| * Registers the end of an Interrupt Service Routine. | |
| * | |
| * The parameter isTaskSwitchRequired indicates if the interrupt has requested a | |
| * task-switch (= 1) or if the interrupt returns to the earlier context (= 0) | |
| * | |
| * Example: | |
| * #define PRIO_ISR_TIMER1 3 // the hardware priority of the interrupt | |
| * ... | |
| * vTraceSetISRProperties("ISRTimer1", PRIO_ISR_TIMER1); | |
| * ... | |
| * void ISR_handler() | |
| * { | |
| * vTraceStoreISRBegin("ISRTimer1"); | |
| * ... | |
| * vTraceStoreISREndManual(0); | |
| * } | |
| * | |
| ******************************************************************************/ | |
| void vTraceStoreISREndManual(int isTaskSwitchRequired); | |
| /******************************************************************************* | |
| * vTraceInstanceFinishNow | |
| * | |
| * Creates an event that ends the current task instance at this very instant. | |
| * This makes the viewer to splits the current fragment at this point and begin | |
| * a new actor instance, even if no task-switch has occurred. | |
| *****************************************************************************/ | |
| void vTraceInstanceFinishedNow(void); | |
| /******************************************************************************* | |
| * vTraceInstanceFinishedNext | |
| * | |
| * Marks the current "task instance" as finished on the next kernel call. | |
| * | |
| * If that kernel call is blocking, the instance ends after the blocking event | |
| * and the corresponding return event is then the start of the next instance. | |
| * If the kernel call is not blocking, the viewer instead splits the current | |
| * fragment right before the kernel call, which makes this call the first event | |
| * of the next instance. | |
| *****************************************************************************/ | |
| void vTraceInstanceFinishedNext(void); | |
| /******************************************************************************/ | |
| /*** INTERNAL FUNCTIONS *******************************************************/ | |
| /******************************************************************************/ | |
| /* Saves a symbol name (task name etc.) in symbol table */ | |
| void vTraceSaveSymbol(void *address, const char *name); | |
| /* Deletes a symbol name (task name etc.) from symbol table */ | |
| void vTraceDeleteSymbol(void *address); | |
| /* Saves an object data entry (task base priority) in object data table */ | |
| void vTraceSaveObjectData(void *address, uint32_t data); | |
| /* Removes an object data entry (task base priority) from object data table */ | |
| void vTraceDeleteObjectData(void *address); | |
| /* Store an event with zero parameters (event ID only) */ | |
| void vTraceStoreEvent0(uint16_t eventID); | |
| /* Store an event with one 32-bit parameter (pointer address or an int) */ | |
| void vTraceStoreEvent1(uint16_t eventID, uint32_t param1); | |
| /* Store an event with two 32-bit parameters */ | |
| void vTraceStoreEvent2(uint16_t eventID, uint32_t param1, uint32_t param2); | |
| /* Store an event with three 32-bit parameters */ | |
| void vTraceStoreEvent3( uint16_t eventID, | |
| uint32_t param1, | |
| uint32_t param2, | |
| uint32_t param3); | |
| /* Stores an event with <nParam> 32-bit integer parameters */ | |
| void vTraceStoreEvent(int nParam, uint16_t EventID, ...); | |
| /* Stories an event with a string and <nParam> 32-bit integer parameters */ | |
| void vTraceStoreStringEvent(int nArgs, uint16_t eventID, const char* str, ...); | |
| /* The data structure for commands (a bit overkill) */ | |
| typedef struct | |
| { | |
| unsigned char cmdCode; | |
| unsigned char param1; | |
| unsigned char param2; | |
| unsigned char param3; | |
| unsigned char param4; | |
| unsigned char param5; | |
| unsigned char checksumLSB; | |
| unsigned char checksumMSB; | |
| } TracealyzerCommandType; | |
| /* Checks if the provided command is a valid command */ | |
| int isValidCommand(TracealyzerCommandType* cmd); | |
| /* Executed the received command (Start or Stop) */ | |
| void processCommand(TracealyzerCommandType* cmd); | |
| /* Backwards compatibility macros with old recorder */ | |
| #define vTraceInitTraceData() Trace_Init() | |
| #define uiTraceStart() (1) | |
| #define vTraceStart() | |
| #define vTraceStop() | |
| #else /*(USE_TRACEALYZER_RECORDER == 1)*/ | |
| #define vTraceStoreEvent0(e) | |
| #define vTraceStoreEvent1(e, param1) | |
| #define vTraceStoreEvent2(e, param1, param2) | |
| #define vTraceStoreEvent3(e, param1, param2, param3) | |
| #define vTraceStoreUserEventChannelName(x) 0 | |
| #define vTracePrint(chn, ...) | |
| #define vTracePrintF(chn, ...) | |
| #define vTraceInstanceFinishedNow() | |
| #define vTraceInstanceFinishedNext() | |
| #define vTraceStoreISRBegin(x) | |
| #define vTraceStoreISREnd() | |
| #define vTraceStoreISREndManual(x) | |
| #define vTraceSetISRProperties(a, b) | |
| #define vTraceStoreKernelObjectName(a, b) | |
| /* Backwards compatibility macros with old recorder */ | |
| #define vTraceInitTraceData() | |
| #define uiTraceStart() (1) | |
| #define vTraceStart() | |
| #define vTraceStop() | |
| #endif /*(USE_TRACEALYZER_RECORDER == 1)*/ | |
| extern void psfError(int errCode); | |
| #define PSF_ASSERT(_assert, _err) if (! (_assert)){ psfError(_err); return; } | |
| #define PSF_ERROR_NONE 0 | |
| #define PSF_ERROR_EVENT_CODE_TOO_LARGE 1 | |
| #define PSF_ERROR_ISR_NESTING_OVERFLOW 2 | |
| #ifdef __cplusplus | |
| } | |
| #endif | |
| #endif /* _TRC_RECORDER_H */ |