Line data Source code
1 0 : /* 2 : * Copyright (c) 2024 Nordic Semiconductor ASA 3 : * 4 : * SPDX-License-Identifier: Apache-2.0 5 : */ 6 : 7 : #ifndef ZEPHYR_INCLUDE_LOGGING_LOG_FRONTEND_STMESP_DEMUX_H_ 8 : #define ZEPHYR_INCLUDE_LOGGING_LOG_FRONTEND_STMESP_DEMUX_H_ 9 : 10 : #include <zephyr/kernel.h> 11 : #include <zephyr/sys/mpsc_packet.h> 12 : 13 : #ifdef __cplusplus 14 : extern "C" { 15 : #endif 16 : 17 : /** 18 : * @defgroup log_frontend_stmesp_apis Trace and Debug Domain APIs 19 : * @{ 20 : * @} 21 : * @defgroup log_frontend_stpesp_demux_apis Logging frontend STMESP Demultiplexer API 22 : * @ingroup log_frontend_stmesp_apis 23 : * @{ 24 : */ 25 : 26 : /** @brief Bits used to store major index. */ 27 1 : #define LOG_FRONTEND_STMESP_DEMUX_MAJOR_BITS 3 28 : 29 : /** @brief Bits used to store severity level. */ 30 1 : #define LOG_FRONTEND_STMESP_DEMUX_LEVEL_BITS 3 31 : 32 : /** @brief Bits used to store total length. */ 33 1 : #define LOG_FRONTEND_STMESP_DEMUX_TLENGTH_BITS 16 34 : 35 : /** @brief Bits used to store package length. */ 36 1 : #define LOG_FRONTEND_STMESP_DEMUX_PLENGTH_BITS 10 37 : 38 : /** @brief Maximum number of supported majors. */ 39 1 : #define LOG_FRONTEND_STMESP_DEMUX_MAJOR_MAX BIT(LOG_FRONTEND_STMESP_DEMUX_MAJOR_BITS) 40 : 41 : /** @brief Log message type. */ 42 1 : #define LOG_FRONTEND_STMESP_DEMUX_TYPE_LOG 0 43 : 44 : /** @brief Trace point message type. */ 45 1 : #define LOG_FRONTEND_STMESP_DEMUX_TYPE_TRACE_POINT 1 46 : 47 : /** @brief HW event message type. */ 48 1 : #define LOG_FRONTEND_STMESP_DEMUX_TYPE_HW_EVENT 2 49 : 50 : /** @brief Logging message header. */ 51 1 : struct log_frontend_stmesp_demux_log_header { 52 : /** Major index. */ 53 1 : uint32_t major : LOG_FRONTEND_STMESP_DEMUX_MAJOR_BITS; 54 : 55 : /** Severity level. */ 56 1 : uint32_t level : LOG_FRONTEND_STMESP_DEMUX_LEVEL_BITS; 57 : 58 : /** Total length excluding this header. */ 59 1 : uint32_t total_len : LOG_FRONTEND_STMESP_DEMUX_TLENGTH_BITS; 60 : 61 : /** Hexdump data length. */ 62 1 : uint32_t package_len : LOG_FRONTEND_STMESP_DEMUX_PLENGTH_BITS; 63 : }; 64 : 65 : /** @brief Union for writing raw data to the logging message header. */ 66 1 : union log_frontend_stmesp_demux_header { 67 : /** Log header structure. */ 68 1 : struct log_frontend_stmesp_demux_log_header log; 69 : 70 : /** Raw word. */ 71 1 : uint32_t raw; 72 : }; 73 : 74 : /** @brief Generic STP demux packet. */ 75 1 : struct log_frontend_stmesp_demux_packet_generic { 76 : /** Data for MPSC packet handling. */ 77 1 : MPSC_PBUF_HDR; 78 : 79 : /** Type. */ 80 1 : uint64_t type: 2; 81 : 82 : /** Flag indicating if packet is valid. */ 83 1 : uint64_t content_invalid: 1; 84 : }; 85 : 86 : /** @brief Packet with logging message. */ 87 1 : struct log_frontend_stmesp_demux_log { 88 : /** Data for MPSC packet handling. */ 89 1 : MPSC_PBUF_HDR; 90 : 91 : /** Type. */ 92 1 : uint64_t type: 2; 93 : 94 : /** Flag indicating if packet is valid. */ 95 1 : uint64_t content_invalid: 1; 96 : 97 : /** Timestamp. */ 98 1 : uint64_t timestamp: 59; 99 : 100 : /** Logging header. */ 101 1 : struct log_frontend_stmesp_demux_log_header hdr; 102 : 103 : /** Padding so that data is 8 bytes aligned. */ 104 1 : uint32_t padding; 105 : 106 : /** Content. */ 107 1 : uint8_t data[]; 108 : }; 109 : 110 : /** @brief Packet with trace point. */ 111 1 : struct log_frontend_stmesp_demux_trace_point { 112 : /** Data for MPSC packet handling. */ 113 1 : MPSC_PBUF_HDR; 114 : 115 : /** Type. */ 116 1 : uint64_t type: 2; 117 : 118 : /** Flag indicating if packet is valid. */ 119 1 : uint64_t content_invalid: 1; 120 : 121 : /** Flag indicating if trace point includes data. */ 122 1 : uint64_t has_data: 1; 123 : 124 : /** Timestamp. 54 bits at 40MHz is >14 years. */ 125 1 : uint64_t timestamp: 54; 126 : 127 : /** Major ID. */ 128 1 : uint64_t major: 4; 129 : 130 : /** Source ID - used for compressed logging. */ 131 1 : uint16_t source_id; 132 : 133 : /** ID */ 134 1 : uint16_t id; 135 : 136 : /** Content. */ 137 1 : uint32_t data; 138 : }; 139 : 140 : /** @brief Packet with HW event. */ 141 1 : struct log_frontend_stmesp_demux_hw_event { 142 : /** Data for MPSC packet handling. */ 143 1 : MPSC_PBUF_HDR; 144 : 145 : /** Type. */ 146 1 : uint64_t type: 2; 147 : 148 : /** Flag indicating if packet is valid. */ 149 1 : uint64_t content_invalid: 1; 150 : 151 : /** Timestamp. */ 152 1 : uint64_t timestamp: 59; 153 : 154 : /** HW event ID. */ 155 1 : uint8_t evt; 156 : }; 157 : 158 : /** @brief Union of all packet types. */ 159 1 : union log_frontend_stmesp_demux_packet { 160 : /** Pointer to generic mpsc_pbuf const packet. */ 161 1 : const union mpsc_pbuf_generic *rgeneric; 162 : 163 : /** Pointer to generic mpsc_pbuf packet. */ 164 1 : union mpsc_pbuf_generic *generic; 165 : 166 : /** Pointer to the log message. */ 167 1 : struct log_frontend_stmesp_demux_log *log; 168 : 169 : /** Pointer to the trace point message. */ 170 1 : struct log_frontend_stmesp_demux_trace_point *trace_point; 171 : 172 : /** Pointer to the HW event message. */ 173 1 : struct log_frontend_stmesp_demux_hw_event *hw_event; 174 : 175 : /** Pointer to the generic log_frontend_stmesp_demux packet. */ 176 1 : struct log_frontend_stmesp_demux_packet_generic *generic_packet; 177 : }; 178 : 179 : /** @brief Demultiplexer configuration. */ 180 1 : struct log_frontend_stmesp_demux_config { 181 : /** Array with expected major ID's. */ 182 1 : const uint16_t *m_ids; 183 : 184 : /** Array length. Must be not bigger than @ref LOG_FRONTEND_STMESP_DEMUX_MAJOR_MAX. */ 185 1 : uint32_t m_ids_cnt; 186 : 187 : /** Buffer for storing source ID's. Used for turbo logging. */ 188 1 : uint32_t *source_id_buf; 189 : 190 : /** It must be multiple of number of major ID's count. */ 191 1 : size_t source_id_buf_len; 192 : }; 193 : 194 : /** @brief Initialize the demultiplexer. 195 : * 196 : * @param config Configuration. 197 : * 198 : * @retval 0 on success. 199 : * @retval -EINVAL on invalid configuration. 200 : */ 201 1 : int log_frontend_stmesp_demux_init(const struct log_frontend_stmesp_demux_config *config); 202 : 203 : /** @brief Indicate major opcode in the STPv2 stream. 204 : * 205 : * @param id Master ID. 206 : */ 207 1 : void log_frontend_stmesp_demux_major(uint16_t id); 208 : 209 : /** @brief Indicate channel opcode in the STPv2 stream. 210 : * 211 : * @param id Channel ID. 212 : */ 213 1 : void log_frontend_stmesp_demux_channel(uint16_t id); 214 : 215 : /** @brief Indicate detected packet start (DMTS). 216 : * 217 : * @param data Data. Can be NULL which indicates trace point without data. 218 : * @param ts Timestamp. Can be NULL. 219 : */ 220 1 : int log_frontend_stmesp_demux_packet_start(uint32_t *data, uint64_t *ts); 221 : 222 : /** @brief Indicate optimized log message with no arguments. 223 : * 224 : * @param source_id Source ID. 225 : * @param ts Timestamp. Can be NULL. 226 : */ 227 1 : int log_frontend_stmesp_demux_log0(uint16_t source_id, uint64_t *ts); 228 : 229 : /** @brief Indicate source ID. 230 : * 231 : * @param source_id Source ID. 232 : */ 233 1 : void log_frontend_stmesp_demux_source_id(uint16_t source_id); 234 : 235 : /** @brief Indicate timestamp. 236 : * 237 : * Timestamp is separated from packet start because according to STM spec (3.2.2) 238 : * it is possible that timestamp is assigned to a later packet. 239 : * 240 : * @param ts Timestamp. 241 : */ 242 1 : void log_frontend_stmesp_demux_timestamp(uint64_t ts); 243 : 244 : /** @brief Indicate data. 245 : * 246 : * @param data Data buffer. 247 : * @param len Length. 248 : */ 249 1 : void log_frontend_stmesp_demux_data(uint8_t *data, size_t len); 250 : 251 : /** @brief Indicate packet end (Flag). */ 252 1 : void log_frontend_stmesp_demux_packet_end(void); 253 : 254 : /** @brief Get number of dropped messages and reset the counter. 255 : * 256 : * Message can be dropped if there is no room in the packet buffer. 257 : * 258 : * @return Number of dropped messages. 259 : */ 260 1 : uint32_t log_frontend_stmesp_demux_get_dropped(void); 261 : 262 : /** @brief Claim packet. 263 : * 264 : * Get pointer to the pending packet with logging message. Packet must be freed 265 : * using @ref log_frontend_stmesp_demux_free. 266 : * 267 : * @return Pointer to the packet or NULL. 268 : */ 269 1 : union log_frontend_stmesp_demux_packet log_frontend_stmesp_demux_claim(void); 270 : 271 : /** @brief Free previously claimed packet. 272 : * 273 : * See @ref log_frontend_stmesp_demux_claim. 274 : * 275 : * @param packet Packet. 276 : */ 277 1 : void log_frontend_stmesp_demux_free(union log_frontend_stmesp_demux_packet packet); 278 : 279 : /** @brief Get source name for a turbo log message. 280 : * 281 : * During a boot cooprocessors (FLPR and PPR) are sending location in memory where 282 : * their source data is stored. If application core is an owner of those cores 283 : * it has access to that memory and based on chip ID and source ID it can retrieve 284 : * the source name. 285 : * 286 : * @param m_id Major ID. 287 : * @param s_id Source ID. 288 : * 289 : * @return Pointer to a string which is a source name or unknown name if source name 290 : * cannot be retrieved. 291 : */ 292 1 : const char *log_frontend_stmesp_demux_sname_get(uint32_t m_id, uint16_t s_id); 293 : 294 : /** @brief Check if there are any started but not completed log messages. 295 : * 296 : * @retval True There is no pending started log message. 297 : * @retval False There is pending message. 298 : */ 299 1 : bool log_frontend_stmesp_demux_is_idle(void); 300 : 301 : /** @brief Close any opened messages and mark them as invalid. */ 302 1 : void log_frontend_stmesp_demux_reset(void); 303 : 304 : /** @brief Get maximum buffer utilization. 305 : * 306 : * @retval Non-negative Maximum buffer utilization. 307 : * @retval -ENOTSUP Feature not enabled. 308 : */ 309 1 : int log_frontend_stmesp_demux_max_utilization(void); 310 : 311 : /** 312 : * @} 313 : */ 314 : 315 : #ifdef __cplusplus 316 : } 317 : #endif 318 : 319 : #endif /* ZEPHYR_INCLUDE_LOGGING_LOG_FRONTEND_STMESP_DEMUX_H_ */
