Line data    Source code

       1             : /*
       2             :  *
       3             :  *    Copyright (c) 2020-2021 Project CHIP Authors
       4             :  *    Copyright (c) 2016-2017 Nest Labs, Inc.
       5             :  *    All rights reserved.
       6             :  *
       7             :  *    Licensed under the Apache License, Version 2.0 (the "License");
       8             :  *    you may not use this file except in compliance with the License.
       9             :  *    You may obtain a copy of the License at
      10             :  *
      11             :  *        http://www.apache.org/licenses/LICENSE-2.0
      12             :  *
      13             :  *    Unless required by applicable law or agreed to in writing, software
      14             :  *    distributed under the License is distributed on an "AS IS" BASIS,
      15             :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      16             :  *    See the License for the specific language governing permissions and
      17             :  *    limitations under the License.
      18             :  */
      19             : 
      20             : /**
      21             :  *  @file
      22             :  *      This file defines the circular buffer for TLV
      23             :  *      elements. When used as the backing store for the TLVReader and
      24             :  *      TLVWriter, those classes will work with the wraparound of data
      25             :  *      within the buffer.  Additionally, the TLVWriter will be able
      26             :  *      to continually add top-level TLV elements by evicting
      27             :  *      pre-existing elements.
      28             :  */
      29             : 
      30             : #pragma once
      31             : 
      32             : #include <lib/core/CHIPError.h>
      33             : #include <lib/core/TLVBackingStore.h>
      34             : #include <lib/core/TLVReader.h>
      35             : #include <lib/core/TLVWriter.h>
      36             : #include <lib/support/DLLUtil.h>
      37             : 
      38             : #include <stdint.h>
      39             : #include <stdlib.h>
      40             : 
      41             : namespace chip {
      42             : namespace TLV {
      43             : 
      44             : /**
      45             :  * @class TLVCircularBuffer
      46             :  *
      47             :  * @brief
      48             :  *    TLVCircularBuffer provides circular storage for the
      49             :  *    chip::TLV::TLVWriter and chip::TLVTLVReader.  chip::TLV::TLVWriter is able to write an
      50             :  *    unbounded number of TLV entries to the TLVCircularBuffer
      51             :  *    as long as each individual TLV entry fits entirely within the
      52             :  *    provided storage.  The chip::TLV::TLVReader will read at most the size of
      53             :  *    the buffer, but will accommodate the wraparound within the
      54             :  *    buffer.
      55             :  *
      56             :  */
      57             : class DLL_EXPORT TLVCircularBuffer : public chip::TLV::TLVBackingStore
      58             : {
      59             : public:
      60             :     TLVCircularBuffer(uint8_t * inBuffer, uint32_t inBufferLength);
      61             :     TLVCircularBuffer(uint8_t * inBuffer, uint32_t inBufferLength, uint8_t * inHead);
      62             : 
      63             :     void Init(uint8_t * inBuffer, uint32_t inBufferLength);
      64             :     inline uint8_t * QueueHead() const { return mQueueHead; }
      65        7732 :     inline uint8_t * QueueTail() const { return mQueue + ((static_cast<size_t>(mQueueHead - mQueue) + mQueueLength) % mQueueSize); }
      66        4978 :     inline uint32_t DataLength() const { return mQueueLength; }
      67        3281 :     inline uint32_t AvailableDataLength() const { return mQueueSize - mQueueLength; }
      68        1366 :     inline uint32_t GetTotalDataLength() const { return mQueueSize; }
      69          12 :     inline uint8_t * GetQueue() const { return mQueue; }
      70             : 
      71             :     CHIP_ERROR EvictHead();
      72             : 
      73             :     // chip::TLV::TLVBackingStore overrides:
      74             :     CHIP_ERROR OnInit(TLVReader & reader, const uint8_t *& bufStart, uint32_t & bufLen) override;
      75             :     CHIP_ERROR GetNextBuffer(TLVReader & ioReader, const uint8_t *& outBufStart, uint32_t & outBufLen) override;
      76             :     CHIP_ERROR OnInit(TLVWriter & writer, uint8_t *& bufStart, uint32_t & bufLen) override;
      77             :     CHIP_ERROR GetNewBuffer(TLVWriter & ioWriter, uint8_t *& outBufStart, uint32_t & outBufLen) override;
      78             :     CHIP_ERROR FinalizeBuffer(TLVWriter & ioWriter, uint8_t * inBufStart, uint32_t inBufLen) override;
      79             : 
      80             :     /**
      81             :      *  @typedef CHIP_ERROR (*ProcessEvictedElementFunct)(TLVCircularBuffer &inBuffer, void * inAppData, TLVReader &inReader)
      82             :      *
      83             :      *  A function that is called to process a TLV element prior to it
      84             :      *  being evicted from the chip::TLV::TLVCircularBuffer
      85             :      *
      86             :      *  Functions of this type are used to process a TLV element about
      87             :      *  to be evicted from the buffer.  The function will be given a
      88             :      *  chip::TLV::TLVReader positioned on the element about to be deleted, as
      89             :      *  well as void * context where the user may have provided
      90             :      *  additional environment for the callback.  If the function
      91             :      *  processed the element successfully, it must return
      92             :      *  #CHIP_NO_ERROR ; this signifies to the TLVCircularBuffer
      93             :      *  that the element may be safely evicted.  Any other return
      94             :      *  value is treated as an error and will prevent the
      95             :      *  #TLVCircularBuffer from evicting the element under
      96             :      *  consideration.
      97             :      *
      98             :      *  Note: This callback may be used to force
      99             :      *  TLVCircularBuffer to not evict the element.  This may be
     100             :      *  useful in a number of circumstances, when it is desired to
     101             :      *  have an underlying circular buffer, but not to override any
     102             :      *  elements within it.
     103             :      *
     104             :      *  @param[in] inBuffer  A reference to the buffer from which the
     105             :      *                       eviction takes place
     106             :      *
     107             :      *  @param[in] inAppData A pointer to the user-provided structure
     108             :      *                       containing additional context for this
     109             :      *                       callback
     110             :      *
     111             :      *  @param[in] inReader  A TLVReader positioned at the element to
     112             :      *                       be evicted.
     113             :      *
     114             :      *  @retval #CHIP_NO_ERROR On success. Element will be evicted.
     115             :      *
     116             :      *  @retval other        An error has occurred during the event
     117             :      *                       processing.  The element stays in the
     118             :      *                       buffer.  The write function that
     119             :      *                       triggered this element eviction will
     120             :      *                       fail.
     121             :      */
     122             :     typedef CHIP_ERROR (*ProcessEvictedElementFunct)(TLVCircularBuffer & inBuffer, void * inAppData, TLVReader & inReader);
     123             : 
     124             :     uint32_t mImplicitProfileId;
     125             :     void * mAppData; /**< An optional, user supplied context to be used with the callback processing the evicted element. */
     126             :     ProcessEvictedElementFunct
     127             :         mProcessEvictedElement; /**< An optional, user-supplied callback that processes the element prior to evicting it from the
     128             :                                    circular buffer.  See the ProcessEvictedElementFunct type definition on additional information on
     129             :                                    implementing the mProcessEvictedElement function. */
     130             : 
     131             : protected:
     132             :     /**
     133             :      * @brief
     134             :      *   returns the actual state of what our current available buffer space is
     135             :      *
     136             :      * @param[out] outBufStart The pointer to the current buffer
     137             :      *
     138             :      * @param[out] outBufLen   The available length for writing
     139             :      */
     140             :     void GetCurrentWritableBuffer(uint8_t *& outBufStart, uint32_t & outBufLen) const;
     141             : 
     142             : private:
     143             :     uint8_t * mQueue;
     144             :     uint32_t mQueueSize;
     145             :     uint8_t * mQueueHead;
     146             :     uint32_t mQueueLength;
     147             : };
     148             : 
     149             : class DLL_EXPORT CircularTLVReader : public TLVReader
     150             : {
     151             : public:
     152             :     /**
     153             :      * @brief
     154             :      *   Initializes a TLVReader object to read from a single TLVCircularBuffer
     155             :      *
     156             :      * Parsing begins at the start of the buffer (obtained by the
     157             :      * buffer->Start() position) and continues until the end of the buffer
     158             :      * Parsing may wraparound within the buffer (on any element).  At most
     159             :      * buffer->GetQueueSize() bytes are read out.
     160             :      *
     161             :      * @param[in]    buf   A pointer to a fully initialized TLVCircularBuffer
     162             :      *
     163             :      */
     164        3044 :     void Init(TLVCircularBuffer & buf) { TLVReader::Init(buf, buf.DataLength()); }
     165             : };
     166             : 
     167             : class DLL_EXPORT CircularTLVWriter : public TLVWriter
     168             : {
     169             : public:
     170             :     /**
     171             :      * @brief
     172             :      *   Initializes a TLVWriter object to write from a single TLVCircularBuffer
     173             :      *
     174             :      * Writing begins at the last byte of the buffer.  The number of bytes
     175             :      * to be written is not constrained by the underlying circular buffer:
     176             :      * writing new elements to the buffer will kick out previous elements
     177             :      * as long as an individual top-level TLV structure fits within the
     178             :      * buffer.  For example, writing a 7-byte top-level boolean TLV into a
     179             :      * 7 byte buffer will work indefinitely, but writing an 8-byte TLV
     180             :      * structure will result in an error.
     181             :      *
     182             :      * @param[in]    buf   A pointer to a fully initialized TLVCircularBuffer
     183             :      *
     184             :      */
     185        1084 :     void Init(TLVCircularBuffer & buf) { TLVWriter::Init(buf, UINT32_MAX); }
     186             : };
     187             : 
     188             : } // namespace TLV
     189             : } // namespace chip