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 debug
      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__ */