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_GetTraceTime() is the macro which is called to get the current time 39 // for a trace event. It must be provided by the platform. 40 extern PW_TRACE_TIME_TYPE pw_trace_GetTraceTime(void); 41 42 // pw_trace_GetTraceTimeTicksPerSecond() is the function which is called to 43 // determine the unit of the trace time. It must be provided by the platform. 44 extern size_t pw_trace_GetTraceTimeTicksPerSecond(void); 45 46 // PW_TRACE_GET_TIME_DELTA is te macro which is called to determine 47 // the delta between two PW_TRACE_TIME_TYPE variables. It should return a 48 // delta of the two times, in the same type. 49 // The default implementation just subtracts the two, which is suitable if 50 // values either never wrap, or are unsigned and do not wrap multiple times 51 // between trace events. If either of these are not the case a different 52 // implemention should be used. 53 #ifndef PW_TRACE_GET_TIME_DELTA 54 #define PW_TRACE_GET_TIME_DELTA(last_time, current_time) \ 55 ((current_time) - (last_time)) 56 #ifdef __cplusplus 57 static_assert( 58 std::is_unsigned<PW_TRACE_TIME_TYPE>::value, 59 "Default time delta implementation only works for unsigned time types."); 60 #endif // __cplusplus 61 #endif // PW_TRACE_GET_TIME_DELTA 62 63 // --- Config options for callbacks ---- 64 65 // PW_TRACE_CONFIG_MAX_EVENT_CALLBACKS is the maximum number of event callbacks 66 // which can be registered at a time. 67 #ifndef PW_TRACE_CONFIG_MAX_EVENT_CALLBACKS 68 #define PW_TRACE_CONFIG_MAX_EVENT_CALLBACKS 2 69 #endif // PW_TRACE_CONFIG_MAX_EVENT_CALLBACKS 70 71 // PW_TRACE_CONFIG_MAX_SINKS is the maximum number of encoded event sinks which 72 // can be registered at a time. 73 #ifndef PW_TRACE_CONFIG_MAX_SINKS 74 #define PW_TRACE_CONFIG_MAX_SINKS 2 75 #endif // PW_TRACE_CONFIG_MAX_SINKS 76 77 // --- Config options for locks --- 78 79 // PW_TRACE_LOCK Is is also called when registering and unregistering callbacks 80 // and sinks. 81 #ifndef PW_TRACE_LOCK 82 #define PW_TRACE_LOCK() 83 #endif // PW_TRACE_LOCK 84 85 // PW_TRACE_TRY_LOCK is is called when events need to be emptied from the queue, 86 // if multiple trace events happened at the same time only one task needs to get 87 // this lock and will empty the queue for all tasks, therefore there is no need 88 // to block in trace events. 89 // This should lock the same object as PW_TRACE_LOCK, and be unlocked using 90 // PW_TRACE_UNLOCK 91 // Returns true if lock was acquired and false if the lock is currently held and 92 // could not be aquired. 93 #ifndef PW_TRACE_TRY_LOCK 94 #define PW_TRACE_TRY_LOCK() (true) // Returns true if lock successful 95 #endif // PW_TRACE_TRY_LOCK 96 97 #ifndef PW_TRACE_UNLOCK 98 #define PW_TRACE_UNLOCK() 99 #endif // PW_TRACE_UNLOCK 100 101 // PW_TRACE_QUEUE_* is used to lock while queueing an event, this is a quick 102 // copy operation and was designed to be suitable in a critical section to 103 // avoid unneccessary blocking and task switches. 104 #ifndef PW_TRACE_QUEUE_LOCK 105 #define PW_TRACE_QUEUE_LOCK() 106 #endif // PW_TRACE_QUEUE_LOCK 107 108 #ifndef PW_TRACE_QUEUE_UNLOCK 109 #define PW_TRACE_QUEUE_UNLOCK() 110 #endif // PW_TRACE_QUEUE_UNLOCK 111 112 // --- Config options for optional trace buffer --- 113 114 // PW_TRACE_BUFFER_SIZE_BYTES is the size in bytes of the optional trace buffer. 115 // The buffer is automatically registered at boot if the buffer size is not 0. 116 #ifndef PW_TRACE_BUFFER_SIZE_BYTES 117 #define PW_TRACE_BUFFER_SIZE_BYTES 256 118 #endif // PW_TRACE_BUFFER_SIZE_BYTES 119 120 // PW_TRACE_BUFFER_MAX_BLOCK_SIZE_BYTES indicates the maximum size any 121 // individual encoded trace event could be. This is used internally to buffer up 122 // a sample before saving into the buffer. 123 #ifndef PW_TRACE_BUFFER_MAX_BLOCK_SIZE_BYTES 124 // The below calaculation is provided to help determine a suitable value, using 125 // the max data size bytes. 126 #ifndef PW_TRACE_BUFFER_MAX_DATA_SIZE_BYTES 127 #define PW_TRACE_BUFFER_MAX_DATA_SIZE_BYTES (32) 128 #endif // PW_TRACE_BUFFER_MAX_BLOCK_SIZE_BYTES 129 130 #ifndef PW_TRACE_BUFFER_MAX_HEADER_SIZE_BYTES 131 #define PW_TRACE_BUFFER_MAX_HEADER_SIZE_BYTES \ 132 (pw::varint::kMaxVarint64SizeBytes) + /* worst case delta time varint */ \ 133 (sizeof(uint32_t)) + /* trace token size */ \ 134 (pw::varint::kMaxVarint64SizeBytes) + /* worst case trace id varint */ 135 #endif // PW_TRACE_BUFFER_MAX_HEADER_SIZE_BYTES 136 137 #define PW_TRACE_BUFFER_MAX_BLOCK_SIZE_BYTES \ 138 PW_TRACE_BUFFER_MAX_HEADER_SIZE_BYTES + PW_TRACE_BUFFER_MAX_DATA_SIZE_BYTES 139 #endif // PW_TRACE_BUFFER_MAX_BLOCK_SIZE_BYTES 140