1 // Copyright 2020 The Pigweed Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 4 // use this file except in compliance with the License. You may obtain a copy of 5 // the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12 // License for the specific language governing permissions and limitations under 13 // the License. 14 15 // Configurable options for the tokenized trace module. 16 #pragma once 17 18 // Since not all strings are tokenizeable, labels can be passed as arguments. 19 // PW_TRACE_CONFIG_ARG_LABEL_SIZE_BYTES configures the maximum number of 20 // characters to include, if more are provided the string will be clipped. 21 #ifndef PW_TRACE_CONFIG_ARG_LABEL_SIZE_BYTES 22 #define PW_TRACE_CONFIG_ARG_LABEL_SIZE_BYTES 20 23 #endif // PW_TRACE_CONFIG_ARG_LABEL_SIZE_BYTES 24 25 // PW_TRACE_QUEUE_SIZE_EVENTS configures the number of events which can be 26 // queued up internally. This is needed to support concurrent trace events. 27 #ifndef PW_TRACE_QUEUE_SIZE_EVENTS 28 #define PW_TRACE_QUEUE_SIZE_EVENTS 5 29 #endif // PW_TRACE_QUEUE_SIZE_EVENTS 30 31 // --- Config options for time source ---- 32 33 // PW_TRACE_TIME_TYPE sets the type for trace time. 34 #ifndef PW_TRACE_TIME_TYPE 35 #define PW_TRACE_TIME_TYPE uint32_t 36 #endif // PW_TRACE_TIME_TYPE 37 38 // PW_TRACE_GET_TIME is the macro which is called to get the current time for a 39 // trace event. It's default is to use pw_trace_GetTraceTime() which needs to be 40 // provided by the platform. 41 #ifndef PW_TRACE_GET_TIME 42 #define PW_TRACE_GET_TIME() pw_trace_GetTraceTime() 43 extern PW_TRACE_TIME_TYPE pw_trace_GetTraceTime(void); 44 #endif // PW_TRACE_GET_TIME 45 46 // PW_TRACE_GET_TIME_TICKS_PER_SECOND is the macro which is called to determine 47 // the unit of the trace time. It's default is to use 48 // pw_trace_GetTraceTimeTicksPerSecond() which needs to be provided by the 49 // platform. 50 #ifndef PW_TRACE_GET_TIME_TICKS_PER_SECOND 51 #define PW_TRACE_GET_TIME_TICKS_PER_SECOND() \ 52 pw_trace_GetTraceTimeTicksPerSecond() 53 extern size_t pw_trace_GetTraceTimeTicksPerSecond(void); 54 #endif // PW_TRACE_GET_TIME_TICKS_PER_SECOND 55 56 // PW_TRACE_GET_TIME_DELTA is te macro which is called to determine 57 // the delta between two PW_TRACE_TIME_TYPE variables. It should return a 58 // delta of the two times, in the same type. 59 // The default implementation just subtracts the two, which is suitable if 60 // values either never wrap, or are unsigned and do not wrap multiple times 61 // between trace events. If either of these are not the case a different 62 // implemention should be used. 63 #ifndef PW_TRACE_GET_TIME_DELTA 64 #define PW_TRACE_GET_TIME_DELTA(last_time, current_time) \ 65 ((current_time) - (last_time)) 66 #ifdef __cplusplus 67 static_assert( 68 std::is_unsigned<PW_TRACE_TIME_TYPE>::value, 69 "Default time delta implementation only works for unsigned time types."); 70 #endif // __cplusplus 71 #endif // PW_TRACE_GET_TIME_DELTA 72 73 // --- Config options for callbacks ---- 74 75 // PW_TRACE_CONFIG_MAX_EVENT_CALLBACKS is the maximum number of event callbacks 76 // which can be registered at a time. 77 #ifndef PW_TRACE_CONFIG_MAX_EVENT_CALLBACKS 78 #define PW_TRACE_CONFIG_MAX_EVENT_CALLBACKS 2 79 #endif // PW_TRACE_CONFIG_MAX_EVENT_CALLBACKS 80 81 // PW_TRACE_CONFIG_MAX_SINKS is the maximum number of encoded event sinks which 82 // can be registered at a time. 83 #ifndef PW_TRACE_CONFIG_MAX_SINKS 84 #define PW_TRACE_CONFIG_MAX_SINKS 2 85 #endif // PW_TRACE_CONFIG_MAX_SINKS 86 87 // --- Config options for locks --- 88 89 // PW_TRACE_LOCK Is is also called when registering and unregistering callbacks 90 // and sinks. 91 #ifndef PW_TRACE_LOCK 92 #define PW_TRACE_LOCK() 93 #endif // PW_TRACE_LOCK 94 95 // PW_TRACE_TRY_LOCK is is called when events need to be emptied from the queue, 96 // if multiple trace events happened at the same time only one task needs to get 97 // this lock and will empty the queue for all tasks, therefore there is no need 98 // to block in trace events. 99 // This should lock the same object as PW_TRACE_LOCK, and be unlocked using 100 // PW_TRACE_UNLOCK 101 // Returns true if lock was acquired and false if the lock is currently held and 102 // could not be aquired. 103 #ifndef PW_TRACE_TRY_LOCK 104 #define PW_TRACE_TRY_LOCK() (true) // Returns true if lock successful 105 #endif // PW_TRACE_TRY_LOCK 106 107 #ifndef PW_TRACE_UNLOCK 108 #define PW_TRACE_UNLOCK() 109 #endif // PW_TRACE_UNLOCK 110 111 // PW_TRACE_QUEUE_* is used to lock while queueing an event, this is a quick 112 // copy operation and was designed to be suitable in a critical section to 113 // avoid unneccessary blocking and task switches. 114 #ifndef PW_TRACE_QUEUE_LOCK 115 #define PW_TRACE_QUEUE_LOCK() 116 #endif // PW_TRACE_QUEUE_LOCK 117 118 #ifndef PW_TRACE_QUEUE_UNLOCK 119 #define PW_TRACE_QUEUE_UNLOCK() 120 #endif // PW_TRACE_QUEUE_UNLOCK 121 122 // --- Config options for optional trace buffer --- 123 124 // PW_TRACE_BUFFER_SIZE_BYTES is the size in bytes of the optional trace buffer. 125 // The buffer is automatically registered at boot if the buffer size is not 0. 126 #ifndef PW_TRACE_BUFFER_SIZE_BYTES 127 #define PW_TRACE_BUFFER_SIZE_BYTES 256 128 #endif // PW_TRACE_BUFFER_SIZE_BYTES 129 130 // PW_TRACE_BUFFER_MAX_BLOCK_SIZE_BYTES indicates the maximum size any 131 // individual encoded trace event could be. This is used internally to buffer up 132 // a sample before saving into the buffer. 133 #ifndef PW_TRACE_BUFFER_MAX_BLOCK_SIZE_BYTES 134 // The below calaculation is provided to help determine a suitable value, using 135 // the max data size bytes. 136 #ifndef PW_TRACE_BUFFER_MAX_DATA_SIZE_BYTES 137 #define PW_TRACE_BUFFER_MAX_DATA_SIZE_BYTES (32) 138 #endif // PW_TRACE_BUFFER_MAX_BLOCK_SIZE_BYTES 139 140 #ifndef PW_TRACE_BUFFER_MAX_HEADER_SIZE_BYTES 141 #define PW_TRACE_BUFFER_MAX_HEADER_SIZE_BYTES \ 142 (pw::varint::kMaxVarint64SizeBytes) + /* worst case delta time varint */ \ 143 (sizeof(uint32_t)) + /* trace token size */ \ 144 (pw::varint::kMaxVarint64SizeBytes) + /* worst case trace id varint */ 145 #endif // PW_TRACE_BUFFER_MAX_HEADER_SIZE_BYTES 146 147 #define PW_TRACE_BUFFER_MAX_BLOCK_SIZE_BYTES \ 148 PW_TRACE_BUFFER_MAX_HEADER_SIZE_BYTES + PW_TRACE_BUFFER_MAX_DATA_SIZE_BYTES 149 #endif // PW_TRACE_BUFFER_MAX_BLOCK_SIZE_BYTES 150