1 /* 2 * Copyright (C) 2023 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef CHRE_PLATFORM_SHARED_TRACING_H_ 18 #define CHRE_PLATFORM_SHARED_TRACING_H_ 19 20 #include "chre/target_platform/tracing_util.h" 21 #include "pw_trace/trace.h" 22 23 // Format strings gotten from https://pigweed.dev/pw_trace/#data. 24 // Must be macros for string concatenation at preprocessor time. 25 #define PW_MAP_PREFIX "@pw_py_map_fmt:{" 26 #define PW_MAP_SUFFIX "}" 27 28 /** 29 * Traces an instantaneous event. 30 * 31 * @param label A string literal which describes the trace. 32 * @param group <optional> A string literal to group traces together. 33 * @param trace_id <optional> A uint32_t which groups this trace with others 34 * with the same group and trace_id. 35 * Every trace with a trace_id must also have a 36 * group. 37 * @see https://pigweed.dev/pw_trace/#trace-macros 38 */ 39 #define CHRE_TRACE_INSTANT(label, ...) PW_TRACE_INSTANT(label, ##__VA_ARGS__) 40 41 /** 42 * Used to trace the start of a duration event. Should be paired with a 43 * CHRE_TRACE_END (or CHRE_TRACE_END_DATA) with the same 44 * module/label/group/trace_id. 45 * 46 * @param label A string literal which describes the trace. 47 * @param group <optional> A string literal to group traces together. 48 * @param trace_id <optional> A uint32_t which groups this trace with others 49 * with the same group and trace_id. 50 * Every trace with a trace_id must also have a 51 * group. 52 * @see https://pigweed.dev/pw_trace/#trace-macros 53 */ 54 #define CHRE_TRACE_START(label, ...) PW_TRACE_START(label, ##__VA_ARGS__) 55 56 /** 57 * Used to trace the end of a duration event. Should be paired with a 58 * CHRE_TRACE_START (or CHRE_TRACE_START_DATA) with the same 59 * module/label/group/trace_id. 60 * 61 * @param label A string literal which describes the trace. 62 * @param group <optional> A string literal to group traces together. 63 * @param trace_id <optional> A uint32_t which groups this trace with others 64 * with the same group and trace_id. 65 * Every trace with a trace_id must also have a 66 * group. 67 * @see https://pigweed.dev/pw_trace/#trace-macros 68 */ 69 #define CHRE_TRACE_END(label, ...) PW_TRACE_END(label, ##__VA_ARGS__) 70 71 /** 72 * For the group of CHRE_TRACE_INSTANT_DATA... macros. 73 * Use the appropriate macro which contains the parameters you wish to pass to 74 * the trace. If you wish to specify a group you must use either the 75 * CHRE_TRACE_INSTANT_DATA_GROUP macro or CHRE_TRACE_INSTANT_DATA_TRACE_ID macro 76 * with a trace_id. 77 * 78 * Traces an instantaneous event with data variables or literals passed to the 79 * macro, correlating to the dataFmtString. 80 * 81 * @param label A string literal which describes the trace. 82 * @param group A string literal to group traces together. 83 * Must use CHRE_TRACE_INSTANT_DATA_GROUP or 84 * CHRE_TRACE_INSTANT_DATA_TRACE_ID with a trace_id to use this 85 * parameter. 86 * @param trace_id A uint32_t which groups this trace with others with the same 87 * group and trace_id. 88 * Every trace with a trace_id must also have a group. 89 * Must use CHRE_TRACE_INSTANT_DATA_TRACE_ID to use this 90 * parameter. 91 * @param dataFmtString A string literal which is used to relate data to its 92 * size. Use the defined macros "T_X" for ease of use in 93 * the format specifier. The format string must follow the 94 * format "<field name>:<specifier>,..." (omitting the 95 * final comma) 96 * Ex. "data1:" T_U8 ",data2:" T_I32 97 * @param firstData First data variable. Used to enforce proper usage of this 98 * macro (with at least one data variable). 99 * @param VA_ARGS List of variables holding data in the order specified by the 100 * dataFmtString. 101 * 102 * @see https://pigweed.dev/pw_trace/#trace-macros 103 */ 104 #define CHRE_TRACE_INSTANT_DATA(label, dataFmtString, firstData, ...) \ 105 do { \ 106 CHRE_TRACE_ALLOCATE_AND_POPULATE_DATA_BUFFER(firstData, ##__VA_ARGS__); \ 107 PW_TRACE_INSTANT_DATA(label, PW_MAP_PREFIX dataFmtString PW_MAP_SUFFIX, \ 108 chreTraceDataBuffer, chreTraceDataSize); \ 109 } while (0) 110 111 #define CHRE_TRACE_INSTANT_DATA_GROUP(label, group, dataFmtString, firstData, \ 112 ...) \ 113 do { \ 114 CHRE_TRACE_ALLOCATE_AND_POPULATE_DATA_BUFFER(firstData, ##__VA_ARGS__); \ 115 PW_TRACE_INSTANT_DATA(label, group, \ 116 PW_MAP_PREFIX dataFmtString PW_MAP_SUFFIX, \ 117 chreTraceDataBuffer, chreTraceDataSize); \ 118 } while (0) 119 120 #define CHRE_TRACE_INSTANT_DATA_TRACE_ID(label, group, trace_id, \ 121 dataFmtString, firstData, ...) \ 122 do { \ 123 CHRE_TRACE_ALLOCATE_AND_POPULATE_DATA_BUFFER(firstData, ##__VA_ARGS__); \ 124 PW_TRACE_INSTANT_DATA(label, group, trace_id, \ 125 PW_MAP_PREFIX dataFmtString PW_MAP_SUFFIX, \ 126 chreTraceDataBuffer, chreTraceDataSize); \ 127 } while (0) 128 129 /** 130 * For the group of CHRE_TRACE_START_DATA... macros. 131 * Use the appropriate macro which contains the parameters you wish to pass to 132 * the trace. If you wish to specify a group you must use either the 133 * CHRE_TRACE_START_DATA_GROUP macro or CHRE_TRACE_START_DATA_TRACE_ID macro 134 * with a trace_id. 135 * 136 * Used to trace the start of a duration event with data variables or literals 137 * passed to the macro, correlating to the dataFmtString. This should be paired 138 * with a CHRE_TRACE_END (or CHRE_TRACE_END_DATA) with the same 139 * module/label/group/trace_id to measure the duration of this event. 140 * 141 * @param label A string literal which describes the trace. 142 * @param group A string literal to group traces together. 143 * Must use CHRE_TRACE_START_DATA_GROUP or 144 * CHRE_TRACE_START_DATA_TRACE_ID with a trace_id to use this 145 * parameter. 146 * @param trace_id A uint32_t which groups this trace with others with the same 147 * group and trace_id. 148 * Every trace with a trace_id must also have a group. 149 * Must use CHRE_TRACE_START_DATA_TRACE_ID to use this 150 * parameter. 151 * @param dataFmtString A string literal which is used to relate data to its 152 * size. Use the defined macros "T_X" for ease of use in 153 * the format specifier. The format string must follow the 154 * format "<field name>:<specifier>,..." (omitting the 155 * final comma) 156 * Ex. "data1:" T_U8 ",data2:" T_I32 157 * @param firstData First data variable. Used to enforce proper usage of this 158 * macro (with at least one data variable). 159 * @param VA_ARGS List of variables holding data in the order specified by the 160 * dataFmtString. 161 * 162 * @see https://pigweed.dev/pw_trace/#trace-macros 163 */ 164 #define CHRE_TRACE_START_DATA(label, dataFmtString, firstData, ...) \ 165 do { \ 166 CHRE_TRACE_ALLOCATE_AND_POPULATE_DATA_BUFFER(firstData, ##__VA_ARGS__); \ 167 PW_TRACE_START_DATA(label, PW_MAP_PREFIX dataFmtString PW_MAP_SUFFIX, \ 168 chreTraceDataBuffer, chreTraceDataSize); \ 169 } while (0) 170 171 #define CHRE_TRACE_START_DATA_GROUP(label, group, dataFmtString, firstData, \ 172 ...) \ 173 do { \ 174 CHRE_TRACE_ALLOCATE_AND_POPULATE_DATA_BUFFER(firstData, ##__VA_ARGS__); \ 175 PW_TRACE_START_DATA(label, group, \ 176 PW_MAP_PREFIX dataFmtString PW_MAP_SUFFIX, \ 177 chreTraceDataBuffer, chreTraceDataSize); \ 178 } while (0) 179 180 #define CHRE_TRACE_START_DATA_TRACE_ID(label, group, trace_id, dataFmtString, \ 181 firstData, ...) \ 182 do { \ 183 CHRE_TRACE_ALLOCATE_AND_POPULATE_DATA_BUFFER(firstData, ##__VA_ARGS__); \ 184 PW_TRACE_START_DATA(label, group, trace_id, \ 185 PW_MAP_PREFIX dataFmtString PW_MAP_SUFFIX, \ 186 chreTraceDataBuffer, chreTraceDataSize); \ 187 } while (0) 188 189 /** 190 * For the group of CHRE_TRACE_END_DATA... macros. 191 * Use the appropriate macro which contains the parameters you wish to pass to 192 * the trace. If you wish to specify a group you must use either the 193 * CHRE_TRACE_END_DATA_GROUP macro or CHRE_TRACE_END_DATA_TRACE_ID macro 194 * with a trace_id. 195 * 196 * Used to trace the end of a duration event with data variables or literals 197 * passed to the macro, correlating to the dataFmtString. This should be paired 198 * with a CHRE_TRACE_START (or CHRE_TRACE_START_DATA) with the same 199 * module/label/group/trace_id to measure the duration of this event. 200 * 201 * @param label A string literal which describes the trace. 202 * @param group A string literal to group traces together. 203 * Must use CHRE_TRACE_END_DATA_GROUP or 204 * CHRE_TRACE_END_DATA_TRACE_ID with a trace_id to use this 205 * parameter. 206 * @param trace_id A uint32_t which groups this trace with others with the same 207 * group and trace_id. 208 * Every trace with a trace_id must also have a group. 209 * Must use CHRE_TRACE_END_DATA_TRACE_ID to use this 210 * parameter. 211 * @param dataFmtString A string literal which is used to relate data to its 212 * size. Use the defined macros "T_X" for ease of use in 213 * the format specifier. The format string must follow the 214 * format "<field name>:<specifier>,..." (omitting the 215 * final comma) 216 * Ex. "data1:" T_U8 ",data2:" T_I32 217 * @param firstData First data variable. Used to enforce proper usage of this 218 * macro (with at least one data variable). 219 * @param VA_ARGS List of variables holding data in the order specified by the 220 * dataFmtString. 221 * 222 * @see https://pigweed.dev/pw_trace/#trace-macros 223 */ 224 #define CHRE_TRACE_END_DATA(label, dataFmtString, firstData, ...) \ 225 do { \ 226 CHRE_TRACE_ALLOCATE_AND_POPULATE_DATA_BUFFER(firstData, ##__VA_ARGS__); \ 227 PW_TRACE_END_DATA(label, PW_MAP_PREFIX dataFmtString PW_MAP_SUFFIX, \ 228 chreTraceDataBuffer, chreTraceDataSize); \ 229 } while (0) 230 231 #define CHRE_TRACE_END_DATA_GROUP(label, group, dataFmtString, firstData, ...) \ 232 do { \ 233 CHRE_TRACE_ALLOCATE_AND_POPULATE_DATA_BUFFER(firstData, ##__VA_ARGS__); \ 234 PW_TRACE_END_DATA(label, group, PW_MAP_PREFIX dataFmtString PW_MAP_SUFFIX, \ 235 chreTraceDataBuffer, chreTraceDataSize); \ 236 } while (0) 237 238 #define CHRE_TRACE_END_DATA_TRACE_ID(label, group, trace_id, dataFmtString, \ 239 firstData, ...) \ 240 do { \ 241 CHRE_TRACE_ALLOCATE_AND_POPULATE_DATA_BUFFER(firstData, ##__VA_ARGS__); \ 242 PW_TRACE_END_DATA(label, group, trace_id, \ 243 PW_MAP_PREFIX dataFmtString PW_MAP_SUFFIX, \ 244 chreTraceDataBuffer, chreTraceDataSize); \ 245 } while (0) 246 247 #endif // CHRE_PLATFORM_SHARED_TRACING_H_ 248