1 /* 2 * Copyright (c) 2024 Nordic Semiconductor ASA. 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef ZEPHYR_INCLUDE_DEBUG_MIPI_STP_DECODER_H__ 8 #define ZEPHYR_INCLUDE_DEBUG_MIPI_STP_DECODER_H__ 9 10 #include <zephyr/kernel.h> 11 12 #ifdef __cplusplus 13 extern "C" { 14 #endif 15 16 /** 17 * @defgroup mipi_stp_decoder_apis STP Decoder API 18 * @ingroup os_services 19 * @{ 20 */ 21 22 /** @brief STPv2 opcodes. */ 23 enum mipi_stp_decoder_ctrl_type { 24 STP_DATA4 = 1, 25 STP_DATA8 = 2, 26 STP_DATA16 = 4, 27 STP_DATA32 = 8, 28 STP_DATA64 = 16, 29 STP_DECODER_NULL = 128, 30 STP_DECODER_MASTER, 31 STP_DECODER_MERROR, 32 STP_DECODER_CHANNEL, 33 STP_DECODER_VERSION, 34 STP_DECODER_FREQ, 35 STP_DECODER_GERROR, 36 STP_DECODER_FLAG, 37 STP_DECODER_ASYNC, 38 STP_DECODER_NOT_SUPPORTED, 39 }; 40 41 /** @brief Convert type to a string literal. 42 * 43 * @param _type type 44 * @return String literal. 45 */ 46 #define STP_DECODER_TYPE2STR(_type) \ 47 _type == STP_DATA4 ? "DATA4" : (\ 48 _type == STP_DATA8 ? "DATA8" : (\ 49 _type == STP_DATA16 ? "DATA16" : (\ 50 _type == STP_DATA32 ? "DATA32" : (\ 51 _type == STP_DATA64 ? "DATA64" : (\ 52 _type == STP_DECODER_NULL ? "NULL" : (\ 53 _type == STP_DECODER_MASTER ? "MASTER" : (\ 54 _type == STP_DECODER_MERROR ? "MERROR" : (\ 55 _type == STP_DECODER_CHANNEL ? "CHANNEL" : (\ 56 _type == STP_DECODER_VERSION ? "VERSION" : (\ 57 _type == STP_DECODER_FREQ ? "FREQ" : (\ 58 _type == STP_DECODER_GERROR ? "GERROR" : (\ 59 _type == STP_DECODER_FLAG ? "FLAG" : (\ 60 _type == STP_DECODER_ASYNC ? "ASYNC" : (\ 61 "Unknown")))))))))))))) 62 63 /** @brief Union with data associated with a given STP opcode. */ 64 union mipi_stp_decoder_data { 65 /** ID - used for master and channel. */ 66 uint16_t id; 67 68 /** Frequency. */ 69 uint64_t freq; 70 71 /** Version. */ 72 uint32_t ver; 73 74 /** Error code. */ 75 uint32_t err; 76 77 /** Dummy. */ 78 uint32_t dummy; 79 80 /** Data. */ 81 uint64_t data; 82 }; 83 84 /** @brief Callback signature. 85 * 86 * Callback is called whenever an element from STPv2 stream is decoded. 87 * 88 * @note Callback is called with interrupts locked. 89 * 90 * @param type Type. See @ref mipi_stp_decoder_ctrl_type. 91 * @param data Data. Data associated with a given @p type. 92 * @param ts Timestamp. Present if not NULL. 93 * @param marked Set to true if opcode was marked. 94 */ 95 typedef void (*mipi_stp_decoder_cb)(enum mipi_stp_decoder_ctrl_type type, 96 union mipi_stp_decoder_data data, 97 uint64_t *ts, bool marked); 98 99 /** @brief Decoder configuration. */ 100 struct mipi_stp_decoder_config { 101 /** Indicates that decoder start in out of sync state. */ 102 bool start_out_of_sync; 103 104 /** Callback. */ 105 mipi_stp_decoder_cb cb; 106 }; 107 108 /** @brief Initialize the decoder. 109 * 110 * @param config Configuration. 111 * 112 * @retval 0 On successful initialization. 113 * @retval negative On failure. 114 */ 115 int mipi_stp_decoder_init(const struct mipi_stp_decoder_config *config); 116 117 /** @brief Decode STPv2 stream. 118 * 119 * Function decodes the stream and calls the callback for every decoded element. 120 * 121 * @param data Data. 122 * @param len Data length. 123 * 124 * @retval 0 On successful decoding. 125 * @retval negative On failure. 126 */ 127 int mipi_stp_decoder_decode(const uint8_t *data, size_t len); 128 129 /** @brief Indicate synchronization loss. 130 * 131 * If detected, then decoder starts to look for ASYNC marker and drops all data 132 * until ASYNC is found. Synchronization can be lost when there is data loss (e.g. 133 * due to overflow). 134 */ 135 void mipi_stp_decoder_sync_loss(void); 136 137 /** 138 * @} 139 */ 140 141 #ifdef __cplusplus 142 } 143 #endif 144 145 #endif /* ZEPHYR_INCLUDE_DEBUG_MIPI_STP_DECODER_H__ */ 146
