Line data    Source code

       1              : /*
       2              :  *
       3              :  *    Copyright (c) 2025 Project CHIP Authors
       4              :  *    All rights reserved.
       5              :  *
       6              :  *    Licensed under the Apache License, Version 2.0 (the "License");
       7              :  *    you may not use this file except in compliance with the License.
       8              :  *    You may obtain a copy of the License at
       9              :  *
      10              :  *        http://www.apache.org/licenses/LICENSE-2.0
      11              :  *
      12              :  *    Unless required by applicable law or agreed to in writing, software
      13              :  *    distributed under the License is distributed on an "AS IS" BASIS,
      14              :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      15              :  *    See the License for the specific language governing permissions and
      16              :  *    limitations under the License.
      17              :  */
      18              : #pragma once
      19              : #include <lib/core/TLVCircularBuffer.h>
      20              : #include <lib/support/Span.h>
      21              : #include <tracing/esp32_diagnostic_trace/DiagnosticEntry.h>
      22              : 
      23              : namespace chip {
      24              : namespace Tracing {
      25              : namespace Diagnostics {
      26              : 
      27              : /**
      28              :  * @brief Diagnostic storage class
      29              :  */
      30              : class CircularDiagnosticBuffer : public chip::TLV::TLVCircularBuffer
      31              : {
      32              : public:
      33            3 :     CircularDiagnosticBuffer(uint8_t * buffer, uint32_t bufferLength) : chip::TLV::TLVCircularBuffer(buffer, bufferLength) {}
      34              : 
      35              :     /**
      36              :      * @brief Stores a diagnostic entry in the diagnostic storage buffer.
      37              :      * @param diagnostic  A reference to a `DiagnosticEntry` object that contains
      38              :      *                    the diagnostic data to be stored.
      39              :      * @return CHIP_ERROR  Returns `CHIP_NO_ERROR` if the data is successfully stored,
      40              :      *                     or an appropriate error code in case of failure.
      41              :      */
      42              :     CHIP_ERROR Store(const DiagnosticEntry & diagnostic);
      43              : 
      44              :     /**
      45              :      * @brief Copies diagnostic data from the storage buffer to a payload.
      46              :      *
      47              :      * This method retrieves the stored diagnostic data and copies it into the
      48              :      * provided `payload` buffer. If the buffer is too small to hold all the data,
      49              :      * still method returns the successfully copied entries along with an error code
      50              :      * indicating that the buffer was insufficient.
      51              :      *
      52              :      * @param payload       A reference to a `MutableByteSpan` where the retrieved
      53              :      *                      diagnostic data will be copied.
      54              :      * @param read_entries  A reference to an integer that will hold the total
      55              :      *                      number of successfully read diagnostic entries.
      56              :      *
      57              :      * @retval CHIP_NO_ERROR             If the operation succeeded and all data was copied.
      58              :      * @retval CHIP_ERROR                 If any other failure occurred during the operation.
      59              :      */
      60              :     CHIP_ERROR Retrieve(MutableByteSpan & payload, uint32_t & read_entries);
      61              : 
      62              :     /**
      63              :      * @brief Checks if the diagnostic storage buffer is empty.
      64              :      *
      65              :      * This method checks whether the buffer contains any stored diagnostic data.
      66              :      *
      67              :      * @return bool  Returns `true` if the buffer contains no stored data,
      68              :      *               or `false` if the buffer has data.
      69              :      */
      70              :     bool IsBufferEmpty();
      71              : 
      72              :     /**
      73              :      * @brief Retrieves the size of the data currently stored in the diagnostic buffer.
      74              :      *
      75              :      * This method returns the total size (in bytes) of all diagnostic data that is
      76              :      * currently stored in the buffer.
      77              :      *
      78              :      * @return uint32_t  The size (in bytes) of the stored diagnostic data.
      79              :      */
      80              :     uint32_t GetDataSize();
      81              : 
      82              :     /**
      83              :      * @brief Clears entire buffer
      84              :      */
      85              :     CHIP_ERROR ClearBuffer();
      86              : 
      87              :     /**
      88              :      * @brief Clears buffer up to the specified number of entries
      89              :      */
      90              :     CHIP_ERROR ClearBuffer(uint32_t entries);
      91              : 
      92              : private:
      93              :     chip::TLV::CircularTLVReader mReader;
      94              :     chip::TLV::CircularTLVWriter mWriter;
      95              : };
      96              : 
      97              : } // namespace Diagnostics
      98              : } // namespace Tracing
      99              : } // namespace chip