git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-Plus-Trace/Include/trcKernel.h

   1 /*******************************************************************************\r
   2  * FreeRTOS+Trace v2.3.0 Recorder Library\r
   3  * Percepio AB, www.percepio.com\r
   4  *\r
   5  * trcKernel.h\r
   6  *\r
   7  * Functions used by trcHooks.h, for the FreeRTOS kernel integration.\r
   8  *\r
   9  * Terms of Use\r
  10  * This software is copyright Percepio AB. The recorder library is free for\r
  11  * use together with Percepio products. You may distribute the recorder library\r
  12  * in its original form, including modifications in trcPort.c and trcPort.h\r
  13  * given that these modification are clearly marked as your own modifications\r
  14  * and documented in the initial comment section of these source files. \r
  15  * This software is the intellectual property of Percepio AB and may not be \r
  16  * sold or in other ways commercially redistributed without explicit written \r
  17  * permission by Percepio AB.\r
  18  *\r
  19  * Disclaimer \r
  20  * The trace tool and recorder library is being delivered to you AS IS and \r
  21  * Percepio AB makes no warranty as to its use or performance. Percepio AB does \r
  22  * not and cannot warrant the performance or results you may obtain by using the \r
  23  * software or documentation. Percepio AB make no warranties, express or \r
  24  * implied, as to noninfringement of third party rights, merchantability, or \r
  25  * fitness for any particular purpose. In no event will Percepio AB, its \r
  26  * technology partners, or distributors be liable to you for any consequential, \r
  27  * incidental or special damages, including any lost profits or lost savings, \r
  28  * even if a representative of Percepio AB has been advised of the possibility \r
  29  * of such damages, or for any claim by any third party. Some jurisdictions do \r
  30  * not allow the exclusion or limitation of incidental, consequential or special \r
  31  * damages, or the exclusion of implied warranties or limitations on how long an \r
  32  * implied warranty may last, so the above limitations may not apply to you.\r
  33  *\r
  34  * FreeRTOS+Trace is available as Free Edition and in two premium editions.\r
  35  * You may use the premium features during 30 days for evaluation.\r
  36  * Download FreeRTOS+Trace at http://www.percepio.com/products/downloads/\r
  37  *\r
  38  * Copyright Percepio AB, 2012.\r
  39  * www.percepio.com\r
  40  ******************************************************************************/\r
  41 \r
  42 #ifndef TRCKERNEL_H\r
  43 #define TRCKERNEL_H\r
  44 \r
  45 #include "trcBase.h"\r
  46 \r
  47 /* Internal functions */\r
  48 \r
  49 \r
  50 #if !defined INCLUDE_READY_EVENTS || INCLUDE_READY_EVENTS == 1\r
  51 void vTraceStoreTaskReady(objectHandleType handle);\r
  52 #endif\r
  53 \r
  54 void vTraceStoreTaskswitch(void);\r
  55 \r
  56 void vTraceStoreKernelCall(uint32_t eventcode, traceObjectClass objectClass, uint32_t byteParam); \r
  57 \r
  58 void vTraceStoreKernelCallWithNumericParamOnly(uint32_t evtcode, \r
  59                                                uint16_t param);\r
  60 \r
  61 void vTraceStoreKernelCallWithParam(uint32_t evtcode, traceObjectClass objectClass, \r
  62                                     uint32_t objectNumber, uint8_t param);\r
  63 \r
  64 void vTraceSetTaskInstanceFinished(objectHandleType handle);\r
  65 \r
  66 void vTraceSetPriorityProperty(uint8_t objectclass, uint8_t id, uint8_t value);\r
  67 \r
  68 uint8_t uiTraceGetPriorityProperty(uint8_t objectclass, uint8_t id);\r
  69 \r
  70 void vTraceSetObjectState(uint8_t objectclass, uint8_t id, uint8_t value);\r
  71 \r
  72 uint8_t uiTraceGetObjectState(uint8_t objectclass, uint8_t id);\r
  73 \r
  74 #if (INCLUDE_OBJECT_DELETE == 1)    \r
  75 \r
  76 void vTraceStoreObjectNameOnCloseEvent(objectHandleType handle, \r
  77                                        traceObjectClass objectclass);\r
  78 \r
  79 void vTraceStoreObjectPropertiesOnCloseEvent(objectHandleType handle, \r
  80                                              traceObjectClass objectclass);\r
  81 #endif\r
  82 \r
  83 /* Internal constants for task state */\r
  84 #define TASK_STATE_INSTANCE_NOT_ACTIVE 0\r
  85 #define TASK_STATE_INSTANCE_ACTIVE 1\r
  86 #define TASK_STATE_INSTANCE_MARKED_FINISHED 2\r
  87 \r
  88 extern objectHandleType handle_of_running_task;\r
  89 \r
  90 /* This defines the mapping between FreeRTOS queue types and our internal \r
  91 class IDs */\r
  92 extern traceObjectClass TraceObjectClassTable[5];\r
  93 \r
  94 /*******************************************************************************\r
  95  * The event codes - should match the offline config file.\r
  96  * \r
  97  * Some sections below are encoded to allow for constructions like:\r
  98  *\r
  99  *  vTraceStoreKernelCall(EVENTGROUP_CREATE + objectclass, ...\r
 100  *\r
 101  * The object class ID is given by the three LSB bits, in such cases. Since each \r
 102  * object class has a separate object property table, the class ID is needed to \r
 103  * know what section in the object table to use for getting an object name from\r
 104  * an object handle. \r
 105  ******************************************************************************/\r
 106 \r
 107 #define NULL_EVENT                   (0x00)  /* Ignored in the analysis*/\r
 108 \r
 109 /*******************************************************************************\r
 110  * EVENTGROUP_RE\r
 111  *\r
 112  * Events that indicate that something is ready to execute.\r
 113  ******************************************************************************/\r
 114 #define EVENTGROUP_RE                (NULL_EVENT + 2)                   /*0x02*/\r
 115 #define TR_TASK_READY                (EVENTGROUP_RE + 0)                /*0x02*/\r
 116 \r
 117 /*******************************************************************************\r
 118  * EVENTGROUP_TS\r
 119  *\r
 120  * Events for storing task-switches and interrupts. The RESUME events are \r
 121  * generated if the task/interrupt is already marked active.\r
 122  ******************************************************************************/\r
 123 #define EVENTGROUP_TS                (EVENTGROUP_RE + 2)                /*0x04*/\r
 124 #define TS_ISR_BEGIN                 (EVENTGROUP_TS + 0)                /*0x04*/\r
 125 #define TS_ISR_RESUME                (EVENTGROUP_TS + 1)                /*0x05*/\r
 126 #define TS_TASK_BEGIN                (EVENTGROUP_TS + 2)                /*0x06*/\r
 127 #define TS_TASK_RESUME               (EVENTGROUP_TS + 3)                /*0x07*/\r
 128 \r
 129 /*******************************************************************************\r
 130  * EVENTGROUP_OBJCLOSE_NAME\r
 131  * \r
 132  * About Close Events\r
 133  * When an object is evicted from the object property table (object close), two \r
 134  * internal events are stored (EVENTGROUP_OBJCLOSE_NAME and \r
 135  * EVENTGROUP_OBJCLOSE_PROP), containg the handle-name mapping and object \r
 136  * properties valid up to this point.\r
 137  ******************************************************************************/\r
 138 #define EVENTGROUP_OBJCLOSE_NAME     (EVENTGROUP_TS + 4)                /*0x08*/\r
 139 \r
 140 /*******************************************************************************\r
 141  * EVENTGROUP_OBJCLOSE_PROP\r
 142  * \r
 143  * The internal event carrying properties of deleted objects\r
 144  * The handle and object class of the closed object is not stored in this event, \r
 145  * but is assumed to be the same as in the preceeding CLOSE event. Thus, these \r
 146  * two events must be generated from within a critical section. \r
 147  * When queues are closed, arg1 is the "state" property (i.e., number of \r
 148  * buffered messages/signals).\r
 149  * When actors are closed, arg1 is priority, arg2 is handle of the "instance \r
 150  * finish" event, and arg3 is event code of the "instance finish" event. \r
 151  * In this case, the lower three bits is the object class of the instance finish \r
 152  * handle. The lower three bits are not used (always zero) when queues are \r
 153  * closed since the queue type is given in the previous OBJCLOSE_NAME event.\r
 154  ******************************************************************************/\r
 155 #define EVENTGROUP_OBJCLOSE_PROP     (EVENTGROUP_OBJCLOSE_NAME + 8)     /*0x10*/\r
 156 \r
 157 /*******************************************************************************\r
 158  * EVENTGROUP_CREATE\r
 159  * \r
 160  * The events in this group are used to log Kernel object creations.\r
 161  * The lower three bits in the event code gives the object class, i.e., type of\r
 162  * create operation (task, queue, semaphore, etc).\r
 163  ******************************************************************************/\r
 164 #define EVENTGROUP_CREATE    (EVENTGROUP_OBJCLOSE_PROP + 8)             /*0x18*/\r
 165 \r
 166 /*******************************************************************************\r
 167  * EVENTGROUP_SEND\r
 168  * \r
 169  * The events in this group are used to log Send/Give events on queues, \r
 170  * semaphores and mutexeds The lower three bits in the event code gives the \r
 171  * object class, i.e., what type of object that is operated on (queue, semaphore \r
 172  * or mutex).\r
 173  ******************************************************************************/\r
 174 #define EVENTGROUP_SEND      (EVENTGROUP_CREATE + 8)                    /*0x20*/\r
 175 \r
 176 /*******************************************************************************\r
 177  * EVENTGROUP_RECEIVE\r
 178  * \r
 179  * The events in this group are used to log Receive/Take events on queues, \r
 180  * semaphores and mutexes. The lower three bits in the event code gives the \r
 181  * object class, i.e., what type of object that is operated on (queue, semaphore\r
 182  * or mutex).\r
 183  ******************************************************************************/\r
 184 #define EVENTGROUP_RECEIVE                       (EVENTGROUP_SEND + 8)  /*0x28*/\r
 185 \r
 186 /* Send/Give operations, from ISR */\r
 187 #define EVENTGROUP_SEND_FROM_ISR              (EVENTGROUP_RECEIVE + 8)  /*0x30*/\r
 188 \r
 189 /* Receive/Take operations, from ISR */\r
 190 #define EVENTGROUP_RECEIVE_FROM_ISR     (EVENTGROUP_SEND_FROM_ISR + 8)  /*0x38*/\r
 191 \r
 192 /* "Failed" event type versions of above (timeout, failed allocation, etc) */\r
 193 #define EVENTGROUP_FAILED_KSE         (EVENTGROUP_RECEIVE_FROM_ISR + 8) /*0x40*/\r
 194 \r
 195 /* Failed create calls - memory allocation failed */\r
 196 #define EVENTGROUP_FAILED_CREATE                (EVENTGROUP_FAILED_KSE) /*0x40*/\r
 197 \r
 198 /* Failed send/give - timeout! */\r
 199 #define EVENTGROUP_FAILED_SEND           (EVENTGROUP_FAILED_CREATE + 8) /*0x48*/\r
 200 \r
 201 /* Failed receive/take - timeout! */\r
 202 #define EVENTGROUP_FAILED_RECEIVE          (EVENTGROUP_FAILED_SEND + 8) /*0x50*/\r
 203 \r
 204 /* Failed non-blocking send/give - queue full */\r
 205 #define EVENTGROUP_FAILED_SEND_FROM_ISR (EVENTGROUP_FAILED_RECEIVE + 8) /*0x58*/\r
 206 \r
 207 /* Failed non-blocking receive/take - queue empty */\r
 208 #define EVENTGROUP_FAILED_RECEIVE_FROM_ISR \\r
 209                                   (EVENTGROUP_FAILED_SEND_FROM_ISR + 8) /*0x60*/\r
 210 \r
 211 /* Events when blocking on receive/take */\r
 212 #define EVENTGROUP_BLOCK_ON_RECEIVE \\r
 213                                (EVENTGROUP_FAILED_RECEIVE_FROM_ISR + 8) /*0x68*/\r
 214 \r
 215 /* Events when blocking on send/give */\r
 216 #define EVENTGROUP_BLOCK_ON_SEND     (EVENTGROUP_BLOCK_ON_RECEIVE + 8)  /*0x70*/\r
 217 \r
 218 /* Events on queue peek (receive) */\r
 219 #define EVENTGROUP_PEEK              (EVENTGROUP_BLOCK_ON_SEND + 8)     /*0x78*/\r
 220 \r
 221 /* Events on object delete (vTaskDelete or vQueueDelete) */\r
 222 #define EVENTGROUP_DELETE            (EVENTGROUP_PEEK + 8)              /*0x80*/\r
 223 \r
 224 /* Other events - object class is implied: TASK */\r
 225 #define EVENTGROUP_OTHERS            (EVENTGROUP_DELETE + 8)            /*0x88*/\r
 226 #define TASK_DELAY_UNTIL             (EVENTGROUP_OTHERS + 0)            /*0x88*/\r
 227 #define TASK_DELAY                   (EVENTGROUP_OTHERS + 1)            /*0x89*/\r
 228 #define TASK_SUSPEND                 (EVENTGROUP_OTHERS + 2)            /*0x8A*/\r
 229 #define TASK_RESUME                  (EVENTGROUP_OTHERS + 3)            /*0x8B*/\r
 230 #define TASK_RESUME_FROM_ISR         (EVENTGROUP_OTHERS + 4)            /*0x8C*/\r
 231 #define TASK_PRIORITY_SET            (EVENTGROUP_OTHERS + 5)            /*0x8D*/\r
 232 #define TASK_PRIORITY_INHERIT        (EVENTGROUP_OTHERS + 6)            /*0x8E*/\r
 233 #define TASK_PRIORITY_DISINHERIT     (EVENTGROUP_OTHERS + 7)            /*0x8F*/\r
 234 \r
 235 /* Not yet used */\r
 236 #define EVENTGROUP_FTRACE_PLACEHOLDER    (EVENTGROUP_OTHERS + 8)        /*0x90*/\r
 237 \r
 238 /* User events */\r
 239 #define EVENTGROUP_USEREVENT (EVENTGROUP_FTRACE_PLACEHOLDER + 8)        /*0x98*/\r
 240 #define USER_EVENT (EVENTGROUP_USEREVENT + 0)\r
 241 \r
 242 /* Allow for 0-15 arguments (the number of args is added to event code) */\r
 243 #define USER_EVENT_LAST (EVENTGROUP_USEREVENT + 15)                     /*0xA7*/\r
 244 \r
 245 /*******************************************************************************\r
 246  * XTS Event - eXtended TimeStamp events\r
 247  * The timestamps used in the recorder are "differential timestamps" (DTS), i.e.\r
 248  * the time since the last stored event. The DTS fields are either 1 or 2 bytes \r
 249  * in the other events, depending on the bytes available in the event struct. \r
 250  * If the time since the last event (the DTS) is larger than allowed for by \r
 251  * the DTS field of the current event, an XTS event is inserted immidiatly \r
 252  * before the original event. The XTS event contains up to 3 additional bytes \r
 253  * of the DTS value - the higher bytes of the true DTS value. The lower 1-2 \r
 254  * bytes are stored in the normal DTS field. \r
 255  * There are two types of XTS events, XTS8 and XTS16. An XTS8 event is stored \r
 256  * when there is only room for 1 byte (8 bit) DTS data in the original event, \r
 257  * which means a limit of 0xFF (255). The XTS16 is used when the original event \r
 258  * has a 16 bit DTS field and thereby can handle values up to 0xFFFF (65535).\r
 259  * \r
 260  * Using a very high frequency time base can result in many XTS events. \r
 261  * Preferably, the time between two OS ticks should fit in 16 bits, i.e.,\r
 262  * at most 65535. If your time base has a higher frequency, you can define\r
 263  * the TRACE\r
 264  ******************************************************************************/\r
 265 \r
 266 #define EVENTGROUP_SYS (EVENTGROUP_USEREVENT + 16)                      /*0xA8*/\r
 267 #define XTS8 (EVENTGROUP_SYS + 0)                                       /*0xA8*/\r
 268 #define XTS16 (EVENTGROUP_SYS + 1)                                      /*0xA9*/\r
 269 \r
 270 #define EVENT_BEING_WRITTEN (EVENTGROUP_SYS + 2)                        /*0xAA*/\r
 271 \r
 272 #define RESERVED_DUMMY_CODE (EVENTGROUP_SYS + 3)                        /*0xAB*/\r
 273 \r
 274 #endif\r