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_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           0 : 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_MAJOR,
      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           1 : #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_MAJOR ? "MAJOR" : (\
      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           1 : union mipi_stp_decoder_data {
      65             :         /** ID - used for major and channel. */
      66           1 :         uint16_t id;
      67             : 
      68             :         /** Frequency. */
      69           1 :         uint64_t freq;
      70             : 
      71             :         /** Version. */
      72           1 :         uint32_t ver;
      73             : 
      74             :         /** Error code. */
      75           1 :         uint32_t err;
      76             : 
      77             :         /** Dummy. */
      78           1 :         uint32_t dummy;
      79             : 
      80             :         /** Data. */
      81           1 :         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           1 : 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           1 : struct mipi_stp_decoder_config {
     101             :         /** Indicates that decoder start in out of sync state. */
     102           1 :         bool start_out_of_sync;
     103             : 
     104             :         /** Callback. */
     105           1 :         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           1 : 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           1 : 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           1 : 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__ */